Re: [PATCH v3 02/16] docs: admin-guide: reporting-issues.rst: replace some characters

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Em Sun, 16 May 2021 12:28:06 +0200
Thorsten Leemhuis <linux@leemhuis.info> escreveu:

> Lo! On one hand I think it would be good to fix the tools to make them
> understand non-breakable spaces in places where the author chose to use
> them,

Fixing it is not trivial ;-)

See, while DocBook, LaTeX and other similar tools allow the author
to specify exactly how the output will be produced, Markup languages 
are not meant to give full control to the author, but, instead, to make
their work easier by letting the toolset to take decisions about line
breaks, font type and size, etc.

In the specific case of Sphinx, the main tool parses the ReST files,
and an output module is responsible to generate the actual output.

So, there's one module for LaTeX, another one for HTML and a
third party one for PDF (we currently don't use the last one).

It is the output module that will actually decide to do line
breaks and to honor the document margins and to add non-breakable
spaces when needed.

When the output is a web page, it shouldn't be a problem to use
unbreakable spaces, provided that the output module is smart enough
to detect it, adding an horizontal scroll bar if needed to avoid
long lines to be simply truncated if the window is smaller than
the lines.

For e-pub, LaTeX and PDF, though, unbreakable spaces should be
replaced by normal ones if the string is too long, or the lines
will simply be truncated, with text loses.

So, while it could be possible to use such characters, extra
care should be taken, as all output formats need to be tested.

Also, as Kernel patches and toolset improvements could change,
for instance, the used font, or a change somewhere could lead
into a different column width, such the tests need to be
repeated from time to time and with different Sphinx versions.

So, this ends by being a maintenance nightmare. Better to live
without those ;-)

> but whatever, their use in that sentence is definitely not
> important, so feel free to add:
> 
> Acked-by: Thorsten Leemhuis <linux@leemhuis.info>
> 
> Thanks for working on this. Ciao, Thorsten

Thanks!
Mauro
> 
> On 16.05.21 12:18, Mauro Carvalho Chehab wrote:
> > The conversion tools used during DocBook/LaTeX/html/Markdown->ReST
> > conversion and some cut-and-pasted text contain some characters that
> > aren't easily reachable on standard keyboards and/or could cause
> > troubles when parsed by the documentation build system.
> > 
> > Replace the occurences of the following characters:
> > 
> > 	- U+00a0 (' '): NO-BREAK SPACE
> > 	  as it can cause lines being truncated on PDF output
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> > ---
> >  Documentation/admin-guide/reporting-issues.rst | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/admin-guide/reporting-issues.rst b/Documentation/admin-guide/reporting-issues.rst
> > index 18d8e25ba9df..d7ac13f789cc 100644
> > --- a/Documentation/admin-guide/reporting-issues.rst
> > +++ b/Documentation/admin-guide/reporting-issues.rst
> > @@ -1248,7 +1248,7 @@ paragraph makes the severeness obvious.
> >  
> >  In case you performed a successful bisection, use the title of the change that
> >  introduced the regression as the second part of your subject. Make the report
> > -also mention the commit id of the culprit. In case of an unsuccessful bisection,
> > +also mention the commit id of the culprit. In case of an unsuccessful bisection,
> >  make your report mention the latest tested version that's working fine (say 5.7)
> >  and the oldest where the issue occurs (say 5.8-rc1).
> >  
> >   



Thanks,
Mauro