Re: [groff] mom manpage

[Bertrand Garrigues]

Hi Ingo, hi Peter,

On Fri, Dec 07 2018 at 08:46:23 PM, Ingo Schwarze <address@hidden> wrote:
> Peter Schaffter wrote on Fri, Dec 07, 2018 at 11:18:32AM -0500:
[...]
>> Bertrand, how do you feel about omitting the local docs, leaving
>> just the pointer to the online docs?  If you're agreeable, I can
>> commit the change.
>
[...]
>
> There are numerous problems are right there:
>
>  * How do i know the documentation is in HTML format in the first place?
>    I have seen software documented in PDF, in PostScript,
>    in various dialects of markdown, in plain text, ...
>  * Of course, each of these require starting a different
>    program and typing a different file name extension.
>  * How do i know the file name to start with is "macrolist"?
>    For some HTML documentation i have seen, the author at least
>    chose to call the starting page "index.html", which is clearly
>    better, but still only one of several possibilities.
>
>  * How do i know what to insert for <docdir>?
[...]

In the main groff(1) man page there is the 'POSITIONS FROM INSTALLATION'
section that documents all the installation directories used by the
groff package.  This man page is generated and therefore lists the
directories that were effectively used by the groff build system on the
current machine.  There is a little thing that I'll fix later (this
section still mention an old Makefile.comm file that no longer exists).

Peter you can mention this section of this manpage in the texinfo doc.

> I'm sorry i'm not very constructive today, but i don't know how to
> fix the texinfo problem either.  But one thing is certain: linking
> to the WWW more prominantly than to the local documentation, or in
> a way that is less likely to fail for the user, is a very bad idea.
> What the user finds on the Web may not even correspond to the version
> of the software that is actually installed.

I think we can keep the reference on the online doc with a little
warning that it may not by in sync with the macro installed.

I've just seen another problem: 'make doc' generates the groff.pdf
manual from texinfo, but it is not installed, which seems illogical to
me.


Regards,

Bertrand