Where do I write a manual entry when creating a deb package? Is there any formatting rule/best practice to respect?
I'm very new to deb package creation. Following some tutorials, I just created a package that installs/executes nicely, so now I'd like to write some documentation so that man myFancyPackage returns something instead of no manual entry for myFancyPackage.
Unfortunately none of the tutorials I found speak about manual creation.
There are lots of methods to build a Debian package, but the current "best practice" is to use the tools provided by Debhelper. In the case of man pages, there is a tool named dh_installman (read its manpage) that is called automatically by dh. If you used dh_make or similar to create a template for your package, then a dh invocation will be in your debian/rules file.
dh_installman works by reading the file debian/manpages, or debian/nameofyourpackage.manpages. This file has a list of paths pointing to the man pages of your package. The paths are relative to the root of your package. Here you have an example of a real package. Then, this program will properly install your man pages in the right directory.
So, to sum up, you only have to create the debian/package.manpages and fill it with the paths to your man pages. These paths have to be relative to the root of your package. If you, the packager, are writing the man pages, then they have to be placed in the Debian/ directory.
Man pages were traditionally composed in a typesetting language called roff using a macro package called an (so the command line was roff -man, sic) but few people write raw roff anymore.
There are various SGML and XML documentation formats which have the capability to generate man page sources, though in this day and age, Markdown is probably gaining ground as the de facto standard for new documentation. The top Google hit for me is https://github.com/remarkjs/remark-man though I would definitely also suggest you look at pandoc.
# NAME
Markdown - popular text markup language
# SYNOPSIS
man markdown
# DESCRIPTION
This is a popular lightweight syntax
to generate styled text from an
editor-friendly text source.
It is used on [Stack Overflow][1],
[Github][2], and increasingly on
blogging and authoring platforms.
[1]: https://stackoverflow.com/
[2]: https://github.com/
I'll also mention POD format, which has a long history in the Perl community, and many features in common with popular, more recent lightweight formats. Unless you have other reasons to like it, I would not choose it for new documentation, but it used to be moderately popular even far outside the Perl world back when it was one of the only options with a simple human-readable source format, obvious semantics, and a versatile and well-maintained toolchain and support ecosystem. Some would probably say it still is.
=head1 NAME
Pod::Example - Example POD document
=head1 SYNOPSIS
pod2man thisdoc.pod >thisdoc.1
=head1 DESCRIPTION
Lightweight syntax for subheads,
hyperlinks, indented lists,
and not much else.
Natively supported in Perl source files
to facilitate a crude form of
literate programming.