Security Section - Modifications

[Phil Bull]

Hi Adam,

On Tue, 2008-01-22 at 23:31 -0500, Adam Sommer wrote:
[...]
> One more small thing I noticed that I didn't with the first patches is
> that when you document a command you start it with "$".  I know this
> represents a shell prompt, but that style isn't used anywhere else in
> the guide except to display some command output.  For example, in the
> Dovecot Server section it's used to show the output of the "telnet
> localhost pop3" command. 
> 
> That's a very small issue, and I was just wondering what you and
> others may think.  Either way I really appreciate the work you've done
> on the Security section.

This is the sort of thing that should be covered in the style guide [1],
so I've made a start on filling-out that section.

While many guides use "$" to signify a command, I think we should only
use it where there is a chance of confusing input with output. For
example:

$ ls
foo.txt
bar.dat

Where output isn't listed, I think it would be better to omit the "$"
sign so that the commands are easier to copy and paste (I always
overshoot with the mouse pointer and highlight/copy the dollar sign
too). There's also a chance that users could think that the "$" is part
of the command and start wondering why the commands don't work.

Even better would be if we could highlight the input command in bold
inside <screen> tags, so we don't have to use a dollar sign at all but
are still differentiating between input and output. I don't have any
ideas on this, though.

Thanks,

Phil

[1] -
https://wiki.ubuntu.com/DocumentationTeam/StyleGuide/DocbookConventions

-- 
Phil Bull
http://www.launchpad.net/people/philbull