What is meta? ×
Meta Stack Exchange is where users like you discuss bugs, features, and support issues that affect the software powering all 131 Stack Exchange communities.

TL;DR: I'm pedantic and am looking for opinions on a good way to format snippets from man pages.


I tend to include snippets from man pages whenever appropriate, and the question that comes to mind often is "what's a good way to format the snippet"?

The easy way out would be to just format it as a block of code which takes care the alignment. E.g.

-P     Never follow symbolic links.  This  is  the  default  behaviour.
       When find examines or prints information a file, and the file is
       a symbolic link, the information used shall be  taken  from  the
       properties of the symbolic link itself.

That's quick and effortless, but it bugs me. Meaningless syntax highlighting creeps in and text-wrapping is affected making it less readable for smaller screens.

I prefer to use block quotes since it it is indeed quoted text. It also allows me to introduce additional formatting to highlight specific text for emphasis, or link keywords to additional resources. However, aligning the output is a slight pain.

Single-level blockquotes don't look like man page output:

-P Never follow symbolic links. This is the default behaviour. When find examines or prints information a file, and the file is a symbolic link, the information used shall be taken from the properties of the symbolic link itself.

while nested quotes introduce too much white space:

-P

Never follow symbolic links. This is the default behaviour. When find examines or prints information a file, and the file is a symbolic link, the information used shall be taken from the properties of the symbolic link itself.

and definition lists don't appear to be formatted differently from plain text (and takes significantly more effort).

-P
Never follow symbolic links. This is the default behaviour. When find examines or prints information a file, and the file is a symbolic link, the information used shall be taken from the properties of the symbolic link itself.

Which if the above do you think is more readable? How would you do it?

P.S. The ideal solution would be to introduce1 the (non standard?) definition list markdown syntax and define a more distinct style for <dl>2. However, that's really too much to ask for a non-issue.

share|improve this question
    
There's a tool that converts in the other direction (write manpages in markdown), but I can't see one for going the other way which would be handy here. –  Flexo Sep 25 '12 at 13:29

1 Answer 1

Just wrap it in a <pre> ... </pre> like this:

<pre>
-P     Never follow symbolic links.  This  is  the  default  behaviour.
       When find examines or prints information a file, and the file is
       a symbolic link, the information used shall be  taken  from  the
       properties of the symbolic link itself.
</pre>

Which results in:

-P     Never follow symbolic links.  This  is  the  default  behaviour.
       When find examines or prints information a file, and the file is
       a symbolic link, the information used shall be  taken  from  the
       properties of the symbolic link itself.
share|improve this answer
    
Thanks. This does prevent unnecessary syntax highlighting, but it still has readability issues in smaller screens. –  Shawn Chin Sep 25 '12 at 12:57
1  
Get a bigger screen? ;) –  Bart Sep 25 '12 at 12:58
    
Nah, I'm not too keen on the Galaxy Note ;) –  Shawn Chin Sep 25 '12 at 12:59
    
This happens with both <code> and <pre> : i.stack.imgur.com/ircTU.png –  Shawn Chin Sep 25 '12 at 13:03
1  
I know. :( That's why I usually keep using the full site, even on mobile. I don't know of a nice solution that would hold up on mobile as well. –  Bart Sep 25 '12 at 13:04
    
Well, we could implement the markdown syntax for definition lists and have it formatted properly (definition indented). –  Shawn Chin Sep 25 '12 at 13:12

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .