<div dir="auto"><div><br><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Jul 18, 2019, 3:54 PM Gedare Bloom <<a href="mailto:gedare@rtems.org">gedare@rtems.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On Thu, Jul 18, 2019 at 11:35 AM Chris Johns <<a href="mailto:chrisj@rtems.org" target="_blank" rel="noreferrer">chrisj@rtems.org</a>> wrote:<br>
><br>
> On 19/7/19 1:32 am, Gedare Bloom wrote:<br>
> > Reviewing the BB doc patch, I realized that we need a style guide for<br>
> > writing docs [1].<br>
><br>
> Thank you for raising this.<br>
><br>
> > We should start to collect Documentation Style notes in a wiki page,<br>
> > and then push it to the docs [1]. If anyone has some initial set of<br>
> > thoughts, it would be good to put them down in reply to this email.<br>
><br>
> We do have <a href="https://git.rtems.org/rtems-docs/tree/README.txt#n393" rel="noreferrer noreferrer" target="_blank">https://git.rtems.org/rtems-docs/tree/README.txt#n393</a>.<br>
><br>
> > My initial question on the BB patch is whether to incorporate the 80<br>
> > char line limit or not.<br>
><br>
> Rules to line wrap at 80 characters are subtle and not straight forward. The<br>
> patch highlights the issue as the long lines appear to me to be copies of<br>
> terminal output. I suspect we need to consider these on a case by case basis to<br>
> weigh up the effect of the long line in the final output vs keeping what is<br>
> present as close to what a user sees. Sometimes you may want the exact output<br>
> and other times an edit to cut the length down does not remove any important<br>
> information. Another factor is the HTML output keeps long code style lines as a<br>
> single line you can scroll and PDF wraps the lines. The wrapping in PDF is<br>
> choice I made to make sure all the text is present and within a page.<br>
><br>
Yes, I understand this issue. I see the rule being one written as '80c<br>
limit, except in "environments"' (Here I use environments in the LaTeX<br>
way, I'm not sure if the same/similar terminology exists, for what<br>
defines a region of text encapsulated in some kind of begin/end block,<br>
e.g., code snippets or verbatim blocks).<br>
<br>
That said, using a hard limit on the line width can cause commit churn<br>
due to reformatting, for example, when you edit an existing paragraph<br>
and extend a line past 80c, this can cause spillover in several/all<br>
subsequent lines of the paragraph.  It is a tricky decision to make<br>
whether to enforce hard breaks or not.<br>
<br>
My recommendation would be to adopt one of two options for narrative<br>
text (not inside an environment):<br>
1. Hard breaks <= 80c, or<br>
2. No line breaks at all, other than at paragraphs.<br>
Adopting one of these will provide consistent look-and-feel to the<br>
writing. There are pros and cons to both approaches. Most text editors<br>
can be configured to support either approach relatively easily, and to<br>
reformat text to one or the other as well.<br></blockquote></div></div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
Gedare<br>
<br>
> Amar and I had many long discussions on this specific issue when I migrated the<br>
> documentation to Sphinx.<br>
><br>
> ><br>
> > [1] <a href="https://docs.rtems.org/branches/master/eng/users-manuals.html#documentation-style-guidelines" rel="noreferrer noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/users-manuals.html#documentation-style-guidelines</a><br>
> ><br>
><br>
> That looks like a good spot to put a guideline.<br>
><br>
> Chris<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank" rel="noreferrer">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a><br>
</blockquote></div></div></div>