On Thu, Jul 18, 2019, 3:54 PM Gedare Bloom <ged...@rtems.org> wrote: > On Thu, Jul 18, 2019 at 11:35 AM 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. > > > Yes, I understand this issue. I see the rule being one written as '80c > limit, except in "environments"' (Here I use environments in the LaTeX > way, I'm not sure if the same/similar terminology exists, for what > defines a region of text encapsulated in some kind of begin/end block, > e.g., code snippets or verbatim blocks). > > That said, using a hard limit on the line width can cause commit churn > due to reformatting, for example, when you edit an existing paragraph > and extend a line past 80c, this can cause spillover in several/all > subsequent lines of the paragraph. It is a tricky decision to make > whether to enforce hard breaks or not. > > My recommendation would be to adopt one of two options for narrative > text (not inside an environment): > 1. Hard breaks <= 80c, or > 2. No line breaks at all, other than at paragraphs. > Adopting one of these will provide consistent look-and-feel to the > writing. There are pros and cons to both approaches. Most text editors > can be configured to support either approach relatively easily, and to > reformat text to one or the other as well. >
I would like option 1. Our paragraphs are generally not huge so the resulting change due to reformatting isn't a big deal. We have been doing this anyway. The raw output is a problem because there is a physical limit on the width on a printed page. Usually it looks awful that way unless you deal with it by hand. This is a no win situation to me. > Gedare > > > 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 >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
