<div dir="auto"><div><br><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Jul 18, 2019, 12:35 PM Chris Johns <<a href="mailto:chrisj@rtems.org">chrisj@rtems.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On 19/7/19 1:32 am, Gedare Bloom wrote:<br>
> Reviewing the BB doc patch, I realized that we need a style guide for<br>
> writing docs [1].<br>
<br>
Thank you for raising this.<br>
<br>
> We should start to collect Documentation Style notes in a wiki page,<br>
> and then push it to the docs [1]. If anyone has some initial set of<br>
> thoughts, it would be good to put them down in reply to this email.<br>
<br>
We do have <a href="https://git.rtems.org/rtems-docs/tree/README.txt#n393" rel="noreferrer noreferrer" target="_blank">https://git.rtems.org/rtems-docs/tree/README.txt#n393</a>.<br>
<br>
> My initial question on the BB patch is whether to incorporate the 80<br>
> char line limit or not.<br>
<br>
Rules to line wrap at 80 characters are subtle and not straight forward. The<br>
patch highlights the issue as the long lines appear to me to be copies of<br>
terminal output. I suspect we need to consider these on a case by case basis to<br>
weigh up the effect of the long line in the final output vs keeping what is<br>
present as close to what a user sees. Sometimes you may want the exact output<br>
and other times an edit to cut the length down does not remove any important<br>
information. Another factor is the HTML output keeps long code style lines as a<br>
single line you can scroll and PDF wraps the lines. The wrapping in PDF is<br>
choice I made to make sure all the text is present and within a page.<br>
<br>
Amar and I had many long discussions on this specific issue when I migrated the<br>
documentation to Sphinx.<br>
<br>
> <br>
> [1] <a href="https://docs.rtems.org/branches/master/eng/users-manuals.html#documentation-style-guidelines" rel="noreferrer noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/users-manuals.html#documentation-style-guidelines</a><br>
> <br>
<br>
That looks like a good spot to put a guideline.<br></blockquote></div></div><div dir="auto"><br></div><div dir="auto">It should be in the SW Engineering Handbook. Is that what that url matches?</div><div dir="auto"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Chris<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank" rel="noreferrer">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
</blockquote></div></div></div>