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

[Joel Sherrill]

On Sun, Feb 24, 2019 at 4:14 PM Chris Johns <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  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. :(


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

>
> 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/20190225/fb32c6d0/attachment-0002.html>