<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Sun, Feb 24, 2019 at 4:14 PM Chris Johns <<a href="mailto:chrisj@rtems.org">chrisj@rtems.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On 22/2/19 5:46 pm, Sebastian Huber wrote:<br>
> On 21/02/2019 22:20, Chris Johns wrote:<br>
>> On 21/2/19 5:13 pm, Sebastian Huber wrote:<br>
>>> On 21/02/2019 03:43,<a href="mailto:chrisj@rtems.org" target="_blank">chrisj@rtems.org</a>  wrote:<br>
>>>> diff --git a/user/bsps/bsps-powerpc.rst b/user/bsps/bsps-powerpc.rst<br>
>>>> index 0ee51d1..365571f 100644<br>
>>>> --- a/user/bsps/bsps-powerpc.rst<br>
>>>> +++ b/user/bsps/bsps-powerpc.rst<br>
>>>> @@ -94,7 +94,7 @@ Boot via U-Boot<br>
>>>>    The application executable file (ELF file) must be converted to an U-Boot<br>
>>>>    image.  Use the following commands:<br>
>>>>    -::<br>
>>>> +.. code-block:: shell<br>
>>>>          powerpc-rtems5-objcopy -O binary app.exe app.bin<br>
>>>>        gzip -9 -f -c app.bin > app.bin.gz<br>
>>> I think the "shell" syntax highlighting is quite erratic. I would rather use<br>
>>> "none".<br>
>> I think a list of shell commands is ok, ie like a script, I suspect it is when<br>
>> there is output mixed in as well.<br>
> <br>
> The colouring of "variables" and numbers is also quite odd sometimes. I found no<br>
> benefit in using it.<br>
<br>
I only updated what was broken, the pigment parser could not detect the format<br>
and generated a warning so I used what we had to be consistent. I agree the<br>
colouring can be off when output is present and it is messy to view.<br>
<br>
There is a default format of `c` so we need to select what is used or we will<br>
always have warnings or we have the possibility of false colouring ...<br>
<br>
 <a href="http://pygments.org/docs/lexers/" rel="noreferrer" target="_blank">http://pygments.org/docs/lexers/</a><br>
<br>
I have not figured out how to disable colouring on specific blocks.<br></blockquote><div><br></div><div>I battled this converting the RSB content for inclusion in the Users Guide.</div><div>It was a pain to pick one which worked and looked right. I don't expect we</div><div>have them all right. And there are so many, I don't know that we will catch</div><div>them all easily. :(</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
>> I have used `$` in shell command lists to indicate a `user` prompt and a command<br>
>> to enter and `#` for `root`, looking at your Quick Start changes you do not use<br>
>> a prompt. Should these be made consistent?<br>
> <br>
> Omitting the '$' or whatever has the benefit that you can copy and past directly<br>
> multiple commands from the example to your terminal.<br>
<br>
Hmm ... I copy and paste commands in terminal windows all the time and my<br>
terminals have a prompt I need to select around cause a prompt is kind of<br>
important. I see this as no different when using our docs when a prompt is present.<br>
<br>
Amar and I had a long discussion about this exact topic when the conversion was<br>
performed and I started on the User Manual. We agreed commands and output was to<br>
be as close to what a user sees. This however is not possible because<br>
differences in hosts, versions of tools, size of output and other things results<br>
in differences but the idea was to show the command entered and output generated<br>
was enough for the user to match what they see with what is documented.<br>
<br>
I see you have varied from what was consistently present. I find this layout ...<br>
<br>
 <a href="https://docs.rtems.org/branches/master/user/start/tools.html" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/user/start/tools.html</a><br>
<br>
... confusing where you have separate unlabelled boxes of commands and then<br>
output requiring the user to assume or learn the next box is output from a<br>
command previously listed.<br>
<br>
How does a new user determine the section is a list of shell commands or output<br>
if they have no idea and are learning?<br>
<br>
We how have 2 styles in this document and I prefer the command and output being<br>
together and with `$` for a user prompt and `#` for a root prompt. If it is<br>
decided this is to change when we should change all cases in the manual.<br></blockquote><div><br></div><div>Any idea which is more common? I don't have a strong opinion. The example you</div><div>posted a link to has text which clearly states "this is the output" so I don't have a</div><div>big issue with that. </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Chris<br>
<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a></blockquote></div></div>