Re: Generating man Pages by help2man can be Problematic when Cross-Compiling, why?
On Tue, 2019-09-03 at 17:45:31 +0500, Andrey Rahmatullin wrote:
> On Tue, Sep 03, 2019 at 07:24:30PM +0700, Bagas Sanjaya wrote:
> > > For executable programs that take arguments, please consider writing a
> > > manual page, rather than expecting users to pass --help or similar. Note
> > > that generating the man page from --help output (with a tool such as
> > > help2man) can range from unhelpful to problematic in cross-compiling
> > > scenarios.
> >
> > I have questions: why can generating man page with help2man be problematic
> > in cross-compiling?
> help2man runs the program which is obviously problematic when the program
> is compiled for a different arch.
In addition this just duplicates the information from --help, which
tends to be pretty terse, while a man page is supposed to be filled
with details of the operation of the program.
> > What if I didn't write man page but expecting users to pass --help
> > instead, or displaying usage syntax when my written program encounters
> > error?
> Then users will need additional actions to get help instead of just
> running "man program".
Right, this is also suboptimal, because it requires the (potential)
user to have a running system with the program installed just to be
able to know how to call it. Compare with being able to go to sites
like man.freebsd.org or manpages.debian.org, and check how programs
work from there.
IMO using help2man (while it provides the above mentioned benefits)
has always translated to me to "cannot be bothered to write proper,
and good documentation", which is a big deciding factor when to use
a specific project or not.
Thanks,
Guillem
Reply to: