Docs Style Guide

[Joel Sherrill]

On Thu, Jul 18, 2019, 3:54 PM Gedare Bloom <gedare at rtems.org> wrote:

> 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.
>

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 at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190718/270165b5/attachment-0002.html>