Currently no uniform method of writing code and directives

[JaminDay]

Not sure if this has been discussed but we need a uniform way of writing/displaying code and directives that will be consistent throughout the manual.

- By code I mean anything we are telling a reader to input into a terminal (i.e. sudo apt-get update)

- By directives I mean anything that directs a user (i.e. click on system->preferences->appearance etc)

I think we need to decide on how we want these to be displayed in the manual, so that we can write them correctly into the latex documents as we go. This should save a heap of time later on.

Things to consider
- do we want code to sit in a 'code block' (similar to a text box), be written in-line in the paragraph, have a line break before and after, or some other method of identifying "this should be written into a terminal".
- should we use quotation marks around directives? If so should they be single or double?
- should there be arrows between directives (such as above example), or comma's, or something else?

Jamin

[Benjamin Humphrey (humphreybc)]

"do we want code to sit in a 'code block' (similar to a text box), be written in-line in the paragraph, have a line break before and after, or some other method of identifying "this should be written into a terminal"."

- Definitely not written in-line. It needs to be separate on its own line. I'm not a huge fan of code blocks - they look ugly. Unless we can beautify our code blocks, then I don't really want that.

I think a line break before and after, and just have the style set to monospace, something that's blindingly obvious as code.

"should we use quotation marks around directives? If so should they be single or double?"

- I don't think we need quotation marks around directives. I'm not sure about this, anyone else got an idea?

"hould there be arrows between directives (such as above example), or comma's, or something else?"

- Once again, arrows would be good, but only if we can make them look nice!

[B1ackcr0w (b1ackcr0w)]

As well as looking professional, I think we need to consider how people will actually use the manual. I think it will be quite rare that folk will actually read the book from front cover to back cover. More often, they will check the index and skip forward to the chapter most relavent to them.

Because of that, I think that if we have a "code block" or other method of showing the input should be into a terminal (or gui or other interface), then it should be just as obvious in chapter 11 as chapter 4.

Maybe we could actually use screenshots of terminal guis where there is a terminal input?

[Joe Burgess (joemburgess)]

I think if we just use screenshots for the terminal input it might be sort of hard to read. Also, it won't be searchable which is a major issue. I will try and throw something together in latex and push it.

[John Hart (jlhart68)]

Rather than a screen shot, maybe a generic graphic could be develped and
the text within the graphic changed to fit the situation?

jmburgess wrote:
> I think if we just use screenshots for the terminal input it might be
> sort of hard to read. Also, it won't be searchable which is a major
> issue. I will try and throw something together in latex and push it.
>
>

[Josh Holland (jshholland)]

WRT code blocks, I do think that it needs setting off in some way from the rest of the text, to mark it as obviously something different (a command to be typed into the terminal)

[Benjamin Humphrey (humphreybc)]

Screenshots won't work, or graphics. Too hard to translate.

Code blocks seem the best way, but pretty code blocks :)

(They're notorious for looking very ugly)

[B1ackcr0w (b1ackcr0w)]

Could we watermark the code boxes with the Lynx that Wolter is doing? That would help differentiate them from the main body text?

[Benjamin Humphrey (humphreybc)]

Yeah maybe... I don't know if LaTeX is THAT powerful :S

[Tom Cantara (tacantara)]

As the possibly newest Ubuntu user on the team, I find the code boxes are
quite effective for training. They take the guesswork out of what verbatim
means (ie do I include the quotation marks).

On Jan 7, 2010 3:10 PM, "Benjamin Humphrey" <email address hidden> wrote:

Yeah maybe... I don't know if LaTeX is THAT powerful :S

-- Currently no uniform method of writing code and directives
https://bugs.launchpad.net/bugs/5040...

Status in Ubuntu Manual: Confirmed Status in Ubuntu Manual main series:
Confirmed

Bug description: Not sure if this has been discussed but we need a uniform
way of writing/displaying...

[Kevin Godby (godbyk)]

I've added some formatting code to handle terminal input/output and inline code.

The terminal environment can be used for code blocks:

  \begin{terminal}
    \prompt \userinput{sudo apt-get install banshee}
    Password: \userinput{s3krE7}
    Installing banshee...
    Banshee installed!
  \end{terminal}

For inline code, use the \code command:

  Type \code{\userinput{banshee}} to start the Banshee music player.

The \prompt command prints a bash user prompt ($), \rootprompt prints a bash root prompt (#), and \userinput will set special formatting for the user's input -- currently set to red for easy editing and debugging.

Let me know if there are other requirements.