Manpage converter removes spaces in literal block

[ggrossetie]

Consider the following manpage that contains a literal block (ASCII art):

= eve(1)
Andrew Stanton
v1.0.0
:doctype: manpage
:manmanual: EVE
:mansource: EVE
:man-linkstyle: pass:[blue R < >]

== Name

eve - analyzes an image to determine if it's a picture of a life form

== Synopsis

....
     ,---.          ,-----.
     |Bob|          |Alice|
     `-+-'          `--+--'
       |    hello      |   
       |-------------->|   
     ,-+-.          ,--+--.
     |Bob|          |Alice|
     `---'          `-----'
....

$ ./bin/asciidoctor eve.adoc -b manpage
$ man ./eve.1

EVE(1)

NAME
       eve - analyzes an image to determine if it's a picture of a life form

SYNOPSIS

                ,---. ,-----.
                |Bob|          |Alice|
                `-+-'          `--+--'
                  |    hello      |
                  |-------------->|
                ,-+-. ,--+--.
                |Bob|          |Alice|
                `---'          `-----'

[mojavelinux]

I'm unaware of how to do this in groff. This post seems to provide some hints https://unix.stackexchange.com/questions/481343/embed-ascii-diagram-in-groff, though it didn't seem to work for me when I tried it.

[0-issue]

The solution here is simple, asciidoctor should just escape spaces. Just doing that seems to work for all ASCII art.

For RGB hex colors, asciidoctor should consider providing a way for user to specify groff defines, I mean embedding raw groff code, just like you have ways for users to embed html/css content.

[mojavelinux]

For RGB hex colors, asciidoctor should consider providing a way for user to specify groff defines, I mean embedding raw groff code, just like you have ways for users to embed html/css content.

If this is something you want, you can create a custom inline macro (or some other type of extension). I don't want to introduce raw groff code into AsciiDoc. That's outside the scope of this language.

[g-branden-robinson]

I'm unaware of how to do this in groff. This post seems to provide some hints https://unix.stackexchange.com/questions/481343/embed-ascii-diagram-in-groff, though it didn't seem to work for me when I tried it.

That didn't work because it was an example for the ms macro package, not the man macro package. If you have groff installed, you can read the man pages for each of these, groff_ms(7) and groff_man(7).

What you want for "ASCII art" in a man page is to turn filling off and select a monospaced font. The EX and EE macros enter and leave this mode.

I will quote their descriptions from groff_man_style(7), including a paragraph of user advice.

     .EX
     .EE    Begin and end example.  After .EX, filling is disabled and a
            constant‐width (monospaced) font is selected.  Calling .EE
            enables filling and restores the previous font.

            Example regions are useful for formatting code, shell
            sessions, and text file contents.  An example region is not
            a “literal mode” of any sort: special character escape
            sequences must still be used to produce correct glyphs for
            ', -, \, ^, `, and ~ (see subsection “Portability” below).
            Sentence endings are still detected and additional inter‐
            sentence space applied.  If the amount of additional inter‐
            sentence spacing is altered, the rendering of, for instance,
            regular expressions using . or ? followed by multiple spaces
            can change.  Use the dummy character escape sequence \&
            before the spaces.

It will be important to keep those rules in mind when generating man output if you want to support fully general ASCII art. Also don't forget that a control character . or ' is still specially recognized by a roff formatter at the start of an input line; the EX macro does not shut that off.

You can find an example of ASCII art in one of groff's own man pages, that for soelim(1).

[mojavelinux]

Use the dummy character escape sequence & before the spaces.

It appears that what fixes it is to introduce \& before a run of more than one space in the literal content. This works without any other changes to the generated markup. That seems like a reasonable fix to make.

(What's strange is that it doesn't seem to be needed in every instance, though it doesn't hurt to use it in every instance).

[g-branden-robinson]

Use the dummy character escape sequence & before the spaces.

It appears that what fixes it is to introduce \& before a run of more than one space in the literal content. This works without any other changes to the generated markup. That seems like a reasonable fix to make.

(What's strange is that it doesn't seem to be needed in every instance, though it doesn't hurt to use it in every instance).

Looking at the commit, it appears that what you're observing is use of the dummy character escape sequence after a period. Like TeX, *roff programs attempt to detect boundaries between sentences, and the period, question mark, and exclamation mark are all sentence-ending punctuation, so the formatter enters a special interpretation state when encountering them at the end of a word.

https://www.gnu.org/software/groff/manual/groff.html.node/Sentences.html

It is indeed harmless to include \& before a run of more than one space in exhibits like this, so your fix looks good to me.