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

[Chris Johns]

On 26/2/19 10:02 am, Joel Sherrill wrote:
> On Mon, Feb 25, 2019 at 4:51 PM Chris Johns <chrisj at rtems.org
> <mailto: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>
>     > <mailto: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>
>     <mailto: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. 

How is a multiline command sequence handled with a few lines of output? For
example ...

 https://docs.rtems.org/branches/master/user/tools/symbols.html#examples

Chris