[PATCH v2] user/bsps : Add documentation for Beagle

[Chris Johns]

On 20/7/19 6:41 am, Gedare Bloom wrote:
> On Fri, Jul 19, 2019 at 11:02 AM Christian Mauderer <list at c-mauderer.de> wrote:
>>
>> On 19/07/2019 18:21, Gedare Bloom wrote:
>>> Looks good to me. I'm currently not able to apply it, verify the doc
>>> build, and push it though. (Workstation issues.)
>>>
>>
>> I agree that it looks OK. Thanks from me too for contributing to the
>> documentation. It's something that most developers don't like to do
>> therefore it's really great that you wrote that.

Pushed.

>>
>> I didn't find any bugs in the instructions while reading through it. I
>> can create a PDF out of it on my Arch Linux machine so I think it should
>> be OK to merge it.
>>
>> You have tried quite a bit till you get an overlay working. If you feel
>> like writing some more documentation, it might would be a good addition
>> to add some notes regarding that too. I think this patch is fine as it
>> is so if you add something please create a second patch.
>>
>> @Gedare: I don't touch the docs repo that often: Is there some defined
>> test process before a commit is added? Or is building a PDF on some
>> random machine enough?
>>
> I don't think the process is well-defined for the docs. However, if
> you built the PDF and it looks good (can you build HTML too?) then go
> ahead and push it.

HTML is the default and always built. You need install to get a suitable
directory tree to review with a `file://....` URL. Details are here but nothing
is specifically said about HTML being always built:

https://git.rtems.org/rtems-docs/tree/README.txt#n336

The rules are not defined and maybe they should be.

1. HTML is always built and must build. Checking HTML is a requirement for
posting a patch for review.

2. PDF is optional because the latex support is not consistent across all build
hosts.

3. Please check the automatically built docs after a push to make sure all
formats look suitable. Post a follow up patch if adjustments are needed.

Comments?

Chris