PROBLEMS(MDOC) MDOC PROBLEMS(MDOC)

escape/solutions/problems
escaping bugs in real-world BSD manuals

  1. On the second Fa line, the opening double quote is missing. Consequently, size_t and *padsize are treated as separate arguments, and the output contains a comma between them. In addition to that, the trailing double quote appears in the output.
  2. The ‘\\’ escape sequence must never be used; ‘\e’ is the correct escape sequence to print a backslash.
    There is no need to escape single quote characters. Actually, the escaping is even wrong, because the ‘\'’ escape sequence is supposed to render as an acute accent, which may not be an ASCII character in all output modes. Besides, the usual way to quote a single character is with the Sq macro.
    The Fl macro should be used when talking about a command line flag.
    Consequently, the sentence should be marked up like this:
    A line is a record separated from the subsequent record 
    by a newline (default) or NUL 
    .Pq Sq \e0 
    character 
    .Fl ( z 
    option).
        
    This renders as:
    A line is a record separated from the subsequent record by a newline (default) or NUL (‘\0’) character (-z option).
  3. An apostroph at the beginning of a line makes the line a macro line. As no such macro is defined, the whole line is lost.
    The proper fix is to prepend a zero-width space to the line:
    A non-zero macro argument makes rules anchored with 
    \&'^' active, while a zero argument makes '^' rules inactive.
        
  4. A blank character at the beginning of a line does make the line a text line as desired, but it also forces a line break before the line, which is not desired here.
September 29, 2015 bsd.lv