pandoc dependency is problematic

[mirabilos]

Hi,

in Debian, we have the problem that pandoc is used to create the manual pages from the Markdown documentation you have in the repository, but pandoc is written in Haskell, and a Haskell compiler is not available for every port (architecture).

I would like to ask you whether you are amenable to one of the two proposals:

1. (preferred) I’ll provide a one-time conversation of the manual pages (basically change from two *.md files in doc/ to a .1 and a .3 file) from Markdown to mdoc (semantic manpage markup, supported by all contemporary manpage viewers), and you merge that and, in the future, update that instead.

2. (if you insist on keeping Markdown) I’ll provide an alternative conversation shell script that produces mdoc from Markdown, and you merge that and ideally use that instead of the pandoc-based one to generate manpages.

As for option 1, it would also be possible to keep the Markdown documentation, but they would, most likely, be out of sync faster than one can blink.

As for option 2, if you don’t adopt the shellscript-based converter and remove the pandoc-based converter, there is a danger that the Markdown grows to something the shellscript won’t expect (it won’t be a truly generic tool, mostly only able to convert your two manpages), so upstream adoption of the shellscript-based tool would be required. (You could in theory keep the pandoc script as an option, but since pandoc is a generic conversion solution, it would always work, while the shellscript might possibly need adaptions when the markdown changes in unexpected ways, so I’d prefer more eyeballs on the output produced from the shellscript.)

I’m volunteering to do the entire work ☺

Would you merge a PR with these changes implemented, and, if yes, which?

---

Backstory: the Debian bug I opened because bind9 no longer compiles on some Linux ports due to lack of libmaxminddb. (Failure to have a nameserver/resolver/host/nslookup/etc. tool is, of course, rather problematic.)

Workaround: I provided a libmaxminddb build without documentation for one of the affected architectures (the one my work desktop runs) for now. This does, however, violate Debian policy, as documentation is desired. It stretches our timeframe from “we need this fixed in libmaxminddb yesterday” to “a fix within a month or so would be perfect”.

[oschwald]

I suspect the Markdown on GitHub is viewed as frequently, if not more frequently, than the man page. Option 1 would preclude that without additional conversion.

Option 2 might work.

We already convert the markdown to roff when we build the release tarballs. However, Debian does not builds its releases from our release tarballs and instead uses the repository directly. I suppose a third option would be to check in the generated roff files when we do a release, and Debian can use those instead.

[mirabilos]

No, Debian cannot use pregenerated files; the rationale being that package builds should not break or produce wrong results if something must be patched (e.g. if someone adds a local spelling fix for the docs), so they should always be rebuilt during package build. Please especially do not check them in.

With option 2, would you be willing to make the shell parser the one upstream uses, so its output gets the most eyeballs?

[oschwald]

I don't quite follow the reasoning on not being able to use the generated files if they were checked in at the time of release and part of the release tag. If Debian needed to add a patch, it could be against the generated file.

@paravoid, thoughts?

[mirabilos]

Gregory Oschwald dixit:

I don't quite follow the reasoning on not being able to use the generated files if they were checked in at the time of release and part

I’ve seen things get out of sync by accident often enough.

of the release tag. If Debian needed to add a patch, it could be against the generated file.

No, really not. DFSG means to work with the preferred form of modification, i.e. the one upstream would also modify. Otherwise, for example, the patch could not be upstreamed, and backporting patches from upstream would also not work.