Control: owner -1 Sérgio Cipriano <sergios...@hotmail.com.br> Thanks to Sergio for accepting ownership of this bug report.
On 08-Mar-2021, Ben Finney wrote:
> We need to obtain (or write) a manual page to install as ‘towncrier(1)’.
For writing a manual page, I recommend reading about the archaic
markup language “roff” and how to write it effectively.
<URL:https://linuxconfig.org/writing-manual-pages-on-linux>
This markup language has significant downsides: It is comparatively
old and there are much better markup languages today; and it is used
for almost nothing else but Unix manual pages.
So it is often tempting to write a manual page in some other markup
language and convert that to roff. I advise against that, though, for
two reasons.
One: The Unix manual system is very well integrated with the specifics
of roff markup. No modern popular markup language has these specific
quirks, and it can be very annoying to write well-formatted manual
pages in any other markup language.
Two: Though roff is quirky and has questionable design choices, it is
quite easy to learn and use, within the limitations of a Unix manual
page.
Bonus third reason: There are good examples of manual pages written
directly in roff, that you can crib from when writing a new one.
I offer as an example, the three manual pages included in the Debian
‘dput’ package. Get their source code, see the ‘doc/man/’ directory
for the manual page source files.
--
\ “Don't worry about what anybody else is going to do. The best |
`\ way to predict the future is to invent it.” —Alan Kay |
_o__) |
Ben Finney <bign...@debian.org>
signature.asc
Description: PGP signature
