Sample Document to Check Sphinx, tex, etc. Install

[Joel Sherrill]

On Wed, Feb 22, 2017 at 3:51 PM, Chris Johns <chrisj at rtems.org> wrote:

> On 23/02/2017 01:16, Joel Sherrill wrote:
>
>> I have been concerned that there is no easy way to know that
>> the host has the complete toolset to build the rtems documentation.
>> I know we are trying to catch things with waf but I was wondering
>> about a short document that just does things that can be quickly
>> checked for correctness.  Examples of:
>>
>> + math formula
>> + citation
>> + code example
>> + ???
>>
>> Otherwise, to be confident, I have to know where to look in the
>> various documents to find examples of things that can break.
>>
>
> Have you looked in the top level README.txt and the Documentation Standard
> section? I documented a number of the features I used. It may need updating.
>
>
I admit to not checking that but that would be the input to what I am
talking about.
If README.txt has an example of using math, citations, and our prominent
patterns,
then README.pdf as generated by the user's tools could be visually checked
easily for correct output.


> There is no template for a directive and more could be added. That
> document is actually in ReST format or is close to it.
>
> This way we can provide a short document and a pre-formatted
>> PDF as a reference.
>>
>
The above sentence is the critical part to me. We should provide a
pre-formatted
version so the user knows what to expect. Either what they generate looks
correct
or a specific piece of the README looks incorrect and it is easy to track
down
what piece of the source code isn't able to be processed correctly.

--joel


>
> Chris
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20170222/5343cccc/attachment-0002.html>