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 <chr...@rtems.org
<mailto:chr...@rtems.org>> wrote:
On 26/2/19 9:32 am, Joel Sherrill wrote:
> On Sun, Feb 24, 2019 at 4:14 PM Chris Johns <chr...@rtems.org
<mailto:chr...@rtems.org>
> <mailto:chr...@rtems.org <mailto:chr...@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,chr...@rtems.org <mailto:chr...@rtems.org>
<mailto:chr...@rtems.org <mailto:chr...@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.hu...@embedded-brains.de
PGP : Public key available on request.
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
