2

In this meta question: Quoted text inline with the rest using code tags is bad. Why? the consensus seems to be that using code tags for things other than code is fine.

Under my answer to this question: strerror(errno) return "Invalid argument" when call read() & write() EJP made the comment:

Please use quote formatting for quotes, and code formatting for code.

(and edited my cut and paste).

In this instance, he's quite right. However, in >90% of the cases where I want to paste from a man-page as a quotation, the quotation tag is a complete pain.

Here are the problems I observe:

  • nroff output is often structured, with indented paragraphs, numbers and so forth.

  • If the manpage contains things like asterisks, markdown attempts to treat them as if they were code.

  • Many of the things in manpages are code, for instance variable names. It takes a while to go an put backticks around each of these. Having everything in monospace in practice looks fine, because it looks like, well, a man-page.

  • Copying to a quote tag is a pain, because you need to undo all the hyphenation, whereas copying to a code tag is nice and easy.

However, against using a code tag, markdown attempts to apply code formatting to the code tag.

What would be really nice is some form of markdown syntax that did monospace blocks, like code, but doesn't highlight them. Is there a way to do that?

Or should I continue using code formatting?

Or should I just suck it up and convert everything manually?

Or should I write a nroff engine to output markdown? (cough)

My answer here illustrates the problem. The originally issue was caused by an HTML formatted manpage being confused. Yet my rendering looks horrible.

Here's an extract from qemu's manpage which I think is hard to represent in markdown (other than by using the code tag):

   ...

   -numa opts
       Simulate a multi node NUMA system. If mem and cpus are omitted,
       resources are split equally.

   -add-fd fd=fd,set=set[,opaque=opaque]
       Add a file descriptor to an fd set.  Valid options are:

       fd=fd
           This option defines the file descriptor of which a duplicate is
           added to fd set.  The file descriptor cannot be stdin, stdout, or
           stderr.

       set=set
           This option defines the ID of the fd set to add the file descriptor
           to.

       opaque=opaque
           This option defines a free-form string that can be used to describe
           fd.

       You can open an image using pre-opened file descriptors from an fd set:

               qemu-system-i386
               -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
               -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
               -drive file=/dev/fdset/2,index=0,media=disk

   -set group.id.arg=value
       Set parameter arg for item id of type group "

   ...
2
  • It's the Smart indents that kill you - nothing like that in any other text engine. But I don't think making SO man page friendly has a top priority. There are tons of reliable sites with entire formatted man pages, and usually one would copy 1 or 2 paragraphs only, right?
    – Jongware
    Jan 27, 2015 at 15:48
  • Sure. Not suggesting it has top priority. One question is whether using code tags for this is OK in the mean time. I'm not sure linking to external sites is a great idea, partly because of the problems with linking, but also because of problems like this stackoverflow.com/questions/28056056/… where the HTML formatting of the man page was in fact the source of the original problem.
    – abligh
    Jan 27, 2015 at 15:54

2 Answers 2

7

You should be using <pre> tags here. It indicates that none of the content in the tags should be treated as markdown, it gives you the monospace font that you want, it maintains whitespace, but it's still not code, not designed to represent code, nor is it going to try to apply any form of prettifying that doesn't make sense for non-code content.

Your example:

   ...

   -numa opts
       Simulate a multi node NUMA system. If mem and cpus are omitted,
       resources are split equally.

   -add-fd fd=fd,set=set[,opaque=opaque]
       Add a file descriptor to an fd set.  Valid options are:

       fd=fd
           This option defines the file descriptor of which a duplicate is
           added to fd set.  The file descriptor cannot be stdin, stdout, or
           stderr.

       set=set
           This option defines the ID of the fd set to add the file descriptor
           to.

       opaque=opaque
           This option defines a free-form string that can be used to describe
           fd.

       You can open an image using pre-opened file descriptors from an fd set:

               qemu-system-i386
               -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
               -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
               -drive file=/dev/fdset/2,index=0,media=disk

   -set group.id.arg=value
       Set parameter arg for item id of type group "

   ...
3
  • I would prefer a code-block with <!-- language: none --> marking. That avoids any trouble with < and >. Jan 27, 2015 at 17:26
  • What exactly is permitted within a Markdown <pre> tag and what is interpreted? In a normal browser &gt; appears to render as > for example.
    – abligh
    Jan 27, 2015 at 18:20
  • @abligh All markdown won't be treated as markdown. Certain types of HTML can be rendered as HTML.
    – Servy
    Jan 27, 2015 at 18:22
0

I've discovered that you can use a quoted form of <pre>. By using ><pre> (that's with an extra close angle-bracket) at the start, you get an effect like the following, which has the advantage of the yellow background (darker grey on meta) for a quotation plus pre-formatting. The only issue is that for reasons that are non-obvious, any blank line needs to be replaced by >. This appears to be quite a good solution.

   ...

   -numa opts
       Simulate a multi node NUMA system. If mem and cpus are omitted,
       resources are split equally.

   -add-fd fd=fd,set=set[,opaque=opaque]
       Add a file descriptor to an fd set.  Valid options are:

   fd=fd
       This option defines the file descriptor of which a duplicate is
       added to fd set.  The file descriptor cannot be stdin, stdout, or
       stderr.

   set=set
       This option defines the ID of the fd set to add the file descriptor
       to.

   opaque=opaque
       This option defines a free-form string that can be used to describe
       fd.

   You can open an image using pre-opened file descriptors from an fd set:

           qemu-system-i386
           -add-fd fd=3,set=2,opaque="rdwr:/path/to/file"
           -add-fd fd=4,set=2,opaque="rdonly:/path/to/file"
           -drive file=/dev/fdset/2,index=0,media=disk
-set group.id.arg=value Set parameter arg for item id of type group " ...
1
  • 3
    Under Firefox, I get an unnecessary vertical scrollbar ...
    – Jongware
    Feb 4, 2015 at 13:08

You must log in to answer this question.

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