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