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 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 _______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
