On Thu, Jul 18, 2019, 12:35 PM Chris Johns <chr...@rtems.org> wrote: > 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. >
It should be in the SW Engineering Handbook. Is that what that url matches? > > Chris > _______________________________________________ > devel mailing list > devel@rtems.org > http://lists.rtems.org/mailman/listinfo/devel >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
