Search code examples
python-sphinxrestructuredtextmanpage

man page - grotty error: character above first line discarded

When building the Chapel language documentation for Chapel with Sphinx as man page, I encounter the following errors:

grotty:<standard input> (path/to/man3/chapel.3) :1756: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :1760: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :1764: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :4794: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :4798: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :4802: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :5505: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :5509: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :5513: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :7137: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :7141: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :7145: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :7892: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :7896: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :7900: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :12168: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :12172: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :12176: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :14254: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :14258: character above first line discarded
grotty:<standard input> (path/to/man3/chapel.3) :14262: character above first line discarded

I can't seem to pin down what is causing this error specifically. Here is a link to the man page I have generated with sphinx. If I can figure out what is causing the error, I imagine I'll be able to modify the source to prevent it in some way.

Solution

  • It turns out this is due to a bug in the grotty program, where it did not accept vertical lines that exceeded a page length. I found this out from a debian bug report back in 2012: https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=673436

    I was able to prevent the error from occurring by prepending my man page file with:

    .if n .pl 2000v

    This effectively makes grotty think the page breaks are actually really big (2000 units), so that it never complains about vertical lines that exceed the default length.

    Hope this helps someone some day.