On Sun, Feb 24, 2019 at 4:14 PM Chris Johns <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 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@rtems.org > http://lists.rtems.org/mailman/listinfo/devel
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
