Docs Style Guide

[Gedare Bloom]

On Thu, Jul 18, 2019 at 11:35 AM Chris Johns <chrisj at 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.

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