[Groff] Elegant -ms and -mpdfmark documents

[Kristaps Dzonsons]

Hello groffers,

I have a survey question regarding -ms and -mpdfmark documents. In
lowdown[1], I emit such documents with the following prologue:

.nr PS 10
.nr GROWPS 3
.DA 2017-09-05
.TL
A Title
.AU
Comrade Foo
.LP
Text here.

The top two lines come from an example given in groff_ms(7), and I'm
afraid aren't the result of a great deal of study on my part. To wit, I
wonder if anybody who uses -ms and -mpdfmark has any suggestions on
settings to improve the legibility of produced documents. I'm not
displeased with the output (see enclosed examples), but curious if I can
do better. For example, the colouring of links, or perhaps the default
header sizes and increments. Or even better, font usage. I don't know!

Thoughts?

Enclosed is the original markdown (index.md), the generated -ms and
-mpdfmark document (index.ms), and the current PDF output from the
following:

lowdown -Dnroff-numbered -s -Tms index.md | \
groff -Tpdf -dpaper=a4 -P-pa4 -ms -mpdfmark > index.pdf

For what it's worth, in lowdown(1) I suggest the following invocation
for producing PS:

groff -k -Dutf8 -t -ms -mpdfmark

This is because markdown documents may contain UTF-8 and lowdown will
produce tbl(7).

Best,

Kristaps

[1] https://kristaps.bsd.lv/lowdown

PS, yes, there are many areas where lowdown can do better with its -ms
output. For example, see the "how you can help" section, but also in
using the pdfmark macros for linking within the document and so on. If
you have suggestions, let me know.

[Deri James]

Post by Kristaps Dzonsons
For example, the colouring of links

You could insert these lines at the top of the .ms file:-

\# These lines set link text and border colours to rgb 0.0 0.3 0.9
.ds PDFHREF.COLOUR 0.0 0.3 0.9
.defcolor pdf:href.colour rgb \*[PDFHREF.COLOUR]
.ds PDFHREF.TEXT.COLOUR pdf:href.colour
\################################################

You don't need to specify -mpdfmark explicitly if you are using -T pdf when you call groff. Since your document only contains external references you do not need to consider forward references in the document, if you did, the groff command line for the pdf device gets a bit more complex, I use something like:-

groff -Tpdf -dPDF.EXPORT=1 -ms -z file.ms 2>&1 | grep \"^\\.ds\" | groff -Tpdf -ms -

If using 'ms'.

Alternatively you could use the command "pdfroff" which uses the postscript device and ghostscript to produce the pdf:-

pdfroff -mspdf --no-toc-relocation index.ms > index.pdf

[mikkel meinike]

Thanks Kristaps Dzonsons for sharing lowdown. I'll be interestet to to know
more about what thats all about and how it looks and so on.

/mikkel

[mikkel meinike]

And in addition. Looking at your document. I was wondering if .TL can be
used more than once in a document just as a centered heading. Since .SH and
.NH are not centered? (sorry for high jacking your threed. But it is such a
small little question :-).

[Kristaps Dzonsons]

Post by mikkel meinike
And in addition. Looking at your document. I was wondering if .TL can be
used more than once in a document just as a centered heading. Since .SH and
.NH are not centered? (sorry for high jacking your threed. But it is such a
small little question :-).

Mikkel, `TL' is just for the title as noted by groff_ms(7), so it's not
appropriate (semantically) as a heading. As for lowdown, it has a
strong focus on using roff (via -ms and -man) because groff is usually
included in base systems. Or mandoc, in my case.

Deri, thanks for the note! I'll switch the examples and notes to use
pdfroff for pdf output. This also solves for the PSPIC problem, where I
could use PSPIC for -Tps, but not for -Tpdf. Was "-mspdf" intentional,
by the way? I can't find mention of it in the manual. The invocation I
think's needed in this case is "pdfroff -i -ms -t -k -Kutf8".

Best,

Kristaps

[Keith Marshall]

Kristaps,

Post by Kristaps Dzonsons
Deri, thanks for the note! I'll switch the examples and notes to use
pdfroff for pdf output. This also solves for the PSPIC problem, where I
could use PSPIC for -Tps, but not for -Tpdf. Was "-mspdf" intentional,
by the way? I can't find mention of it in the manual. The invocation I
think's needed in this case is "pdfroff -i -ms -t -k -Kutf8".

Deri's suggestion to use "-mspdf" was (almost) certainly intentional; it
is a thin wrapper around "-ms", redefining some "ms" internals to make it
play nicer with "-mpdfmark", (the latter being sourced implicitly when
running groff through pdfroff.

[Kristaps Dzonsons]

Post by Keith Marshall

Post by Kristaps Dzonsons
Deri, thanks for the note! I'll switch the examples and notes to use
pdfroff for pdf output. This also solves for the PSPIC problem, where I
could use PSPIC for -Tps, but not for -Tpdf. Was "-mspdf" intentional,
by the way? I can't find mention of it in the manual. The invocation I
think's needed in this case is "pdfroff -i -ms -t -k -Kutf8".

Deri's suggestion to use "-mspdf" was (almost) certainly intentional; it
is a thin wrapper around "-ms", redefining some "ms" internals to make it
play nicer with "-mpdfmark", (the latter being sourced implicitly when
running groff through pdfroff.

Thanks, Keith. The spdf tmac was a good find!

Note that when I run pdfroff without -mpdfmark and with -ms, groff
1.22.3, it does not handle the pdfhref W's at all. (Links are omitted
from the PDF file output.) However, as mentioned, when I use -mspdf, I
don't need to invoke -mpdfmark (or obviously, -ms) directly, given that
it's mso'ing both of the others.

Incidentally, the XN documentation is empty in the current (?)
pdfmark.pdf document[1]. It bears mentioning that the invocation
replaces the subsequent section name as in the NH invocation:

.NH n
.XN The section header
.LP
Now the section...

As before I had misread the macro usage as needing:

.NH n
.XN The section header
The section header <-- (nope)
.
.LP
Now the section...

Moreover, since "XN" accepts only data on the current line, and NH
accepts subsequent lines, this can cause some surprising results with
multi-line section names!

Best,

Kristaps

[1] http://www.chiark.greenend.org.uk/doc/groff/pdf/pdfmark.pdf.gz

[Larry Kollar]

Post by Kristaps Dzonsons
Hello groffers,
I have a survey question regarding -ms and -mpdfmark documents. …
To wit, I
wonder if anybody who uses -ms and -mpdfmark has any suggestions on
settings to improve the legibility of produced documents.

I used ms + pdfmark extensively until a few years ago, when work moved all of us to a content management system (not a very good one, mind you). Personally, I think everyone does what I did — adds their own extensions to -ms to get more control over the output. Sort of like all the variants of Markdown, except that Markdown variants are usually documented somewhere public. :-P

But I digress. If you can package your parameter settings and extensions into one file, you just need an “.so extensions.t" at the beginning of your groff output.


Lowdown looks pretty useful, but I’m a little concerned about the Markdown-hate in the documentation. I use this workflow to produce my fiction books:

MultiMarkdown -> XHTML -> EPUB -> (AZW)[1]
\
XSLT -> *roff -> PDF

One common theme among Markdown variants, they all produce cleaner HTML than I’ve seen from any other tool (except for hand-coded). Piping the output through “tidy -asxhtml -utf8 -numeric” lets it sail right through xsltproc without a hiccup. I’m using *roff (neatroff at the moment, because its output is noticeably more beautiful) instead of XSL:FO for a couple reasons:

1) *roff lets me stick my fingers into the output and even up the bottom margin on each page. I don’t think any of the FO formatters can do that.
2) XSL:FO is tedious as (use the four-letter word you prefer). I wrote a transform just to try it, and it works, but jeez. Set a handful of parameters in -ms, add a few extensions as needed, and let it do the work.

Larry

[1] Amazon converts a submitted EPUB to AZW format for the Kindle. On my end, I only have to worry about EPUB, which is XHTML with a few control files. So the same XHTML provides both EPUB and PDF.