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