[PATCH 6/6] user: Remove nit-picky warnings.

[Joel Sherrill]

On Mon, Feb 25, 2019 at 4:51 PM Chris Johns <chrisj at rtems.org> wrote:

> On 26/2/19 9:32 am, Joel Sherrill wrote:
> > On Sun, Feb 24, 2019 at 4:14 PM Chris Johns <chrisj at rtems.org
> > <mailto:chrisj at rtems.org>> wrote:
> >
> >     On 22/2/19 5:46 pm, Sebastian Huber wrote:
> >     > On 21/02/2019 22:20, Chris Johns wrote:
> >     >> On 21/2/19 5:13 pm, Sebastian Huber wrote:
> >     >>> On 21/02/2019 03:43,chrisj at rtems.org <mailto:chrisj at rtems.org>
> wrote:
> >     >>>> diff --git a/user/bsps/bsps-powerpc.rst
> b/user/bsps/bsps-powerpc.rst
> >     >>>> index 0ee51d1..365571f 100644
> >     >>>> --- a/user/bsps/bsps-powerpc.rst
> >     >>>> +++ b/user/bsps/bsps-powerpc.rst
> >     >>>> @@ -94,7 +94,7 @@ Boot via U-Boot
> >     >>>>    The application executable file (ELF file) must be converted
> to an
> >     U-Boot
> >     >>>>    image.  Use the following commands:
> >     >>>>    -::
> >     >>>> +.. code-block:: shell
> >     >>>>          powerpc-rtems5-objcopy -O binary app.exe app.bin
> >     >>>>        gzip -9 -f -c app.bin > app.bin.gz
> >     >>> I think the "shell" syntax highlighting is quite erratic. I
> would rather use
> >     >>> "none".
> >     >> I think a list of shell commands is ok, ie like a script, I
> suspect it is
> >     when
> >     >> there is output mixed in as well.
> >     >
> >     > The colouring of "variables" and numbers is also quite odd
> sometimes. I
> >     found no
> >     > benefit in using it.
> >
> >     I only updated what was broken, the pigment parser could not detect
> the format
> >     and generated a warning so I used what we had to be consistent. I
> agree the
> >     colouring can be off when output is present and it is messy to view.
> >
> >     There is a default format of `c` so we need to select what is used
> or we will
> >     always have warnings or we have the possibility of false colouring
> ...
> >
> >      http://pygments.org/docs/lexers/
> >
> >     I have not figured out how to disable colouring on specific blocks.
> >
> >
> > I battled this converting the RSB content for inclusion in the Users
> Guide.
> > It was a pain to pick one which worked and looked right. I don't expect
> we
> > have them all right. And there are so many, I don't know that we will
> catch
> > them all easily. :(
> >
>
> A bit more research shows `none` should disable highlighting. I can fix my
> patch
> to use that.
>

That would be good when it isn't something that syntax highlighting is
going to get right.

>
> >     >> I have used `$` in shell command lists to indicate a `user`
> prompt and a
> >     command
> >     >> to enter and `#` for `root`, looking at your Quick Start changes
> you do
> >     not use
> >     >> a prompt. Should these be made consistent?
> >     >
> >     > Omitting the '$' or whatever has the benefit that you can copy and
> past
> >     directly
> >     > multiple commands from the example to your terminal.
> >
> >     Hmm ... I copy and paste commands in terminal windows all the time
> and my
> >     terminals have a prompt I need to select around cause a prompt is
> kind of
> >     important. I see this as no different when using our docs when a
> prompt is
> >     present.
> >
> >     Amar and I had a long discussion about this exact topic when the
> conversion was
> >     performed and I started on the User Manual. We agreed commands and
> output was to
> >     be as close to what a user sees. This however is not possible because
> >     differences in hosts, versions of tools, size of output and other
> things results
> >     in differences but the idea was to show the command entered and
> output generated
> >     was enough for the user to match what they see with what is
> documented.
> >
> >     I see you have varied from what was consistently present. I find
> this layout ...
> >
> >      https://docs.rtems.org/branches/master/user/start/tools.html
> >
> >     ... confusing where you have separate unlabelled boxes of commands
> and then
> >     output requiring the user to assume or learn the next box is output
> from a
> >     command previously listed.
> >
> >     How does a new user determine the section is a list of shell
> commands or output
> >     if they have no idea and are learning?
> >
> >     We how have 2 styles in this document and I prefer the command and
> output being
> >     together and with `$` for a user prompt and `#` for a root prompt.
> If it is
> >     decided this is to change when we should change all cases in the
> manual.
> >
> >
> > Any idea which is more common? I don't have a strong opinion. The
> example you
> > posted a link to has text which clearly states "this is the output" so I
> don't
> > have a big issue with that.
>
> Are you OK with both approaches being used and present in the same doc?
>

Grrr... not really. I like consistency too much.

>
> I know it is small issue but these things tend to get exposed with new
> users.
>

One positive on splitting them is that you get two smaller blocks which
might
format nicer on the page sometimes (no breaks). But the downside is that
you get an odd "this is the output" sentence between the two blocks.

>
> Chris
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190225/5694f88c/attachment-0002.html>