[PATCH 6/6] user: Remove nit-picky warnings.
Sebastian Huber
sebastian.huber at embedded-brains.de
Tue Feb 26 06:42:34 UTC 2019
On 26/02/2019 01:36, Chris Johns wrote:
> 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
I think both presentations make sense. With the $ indication you can
place multiple commands together with the command output in one block.
Using separate blocks for commands and output allows you to simply copy
and based multiple commands to a terminal.
--
Sebastian Huber, embedded brains GmbH
Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone : +49 89 189 47 41-16
Fax : +49 89 189 47 41-09
E-Mail : sebastian.huber at embedded-brains.de
PGP : Public key available on request.
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
More information about the devel
mailing list