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

[Chris Johns]

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

Chris