On 2011-03-17 18:05 -0400, Thomas Dickey wrote:
> On Wed, 16 Mar 2011, Sven Joachim wrote:
>
>> On 2011-03-15 03:54 +0100, Vincent Lefevre wrote:
>>
>>> Package: ncurses-doc
>>> Version: 5.8+20110307-1
>>
>> Note that none of this is new, the same problem exists in the
>> libncurses5-dev package in squeeze and lenny which held the
>> documentation before I split it out to ncurses-doc.
>>
>>> ncurses-doc has /usr/share/doc/ncurses-doc/html/man/*.3x.html files,
>>> but not the corresponding man pages in /usr/share/man/man3.
>>
>> More exactly, the manpages are there, but not under the same names.
>> This is because they are renamed (see man/man_db.renames in the ncurses
>> source tree), while the HTML documentation does not receive such
>> treatment.
>>
>> I don't know why this setup with renaming manpages exists, but it has
>> been around at least since ncurses 4.1, released 1997.
>
> Before that - man_db.renames was added in October 1995. At that point,
> only the files were renamed (no link-fixes), and I added the edit_man.sh
> script in mid-1996 (I seem to recall that was to obsolete some scripting
> in the Debian package - or perhaps I'm recalling some later refinement).
>
> My understanding was that it was done that way to follow some Debian
> guideline.
There is an old thread about that topic from 1996 on debian-devel[1].
The main reason for renaming the manpages has been stated by Richard
Kettlewell[2] and confirmed by Ian Jackson[3]:
,----
| Isn't it a good thing that you can say man <function name> and get the
| right man page, rather than having to say man curs_<function name>,
| though?
`----
>>> Note that some other man pages, e.g. reset(1), have references to
>>> such man pages in the "SEE ALSO" section, so that it is annoying
>>> not to have access to these man pages with "man".
>>
>> This is a fallout from the following change mentioned in NEWS:
>>
>> ,----
>> | 20061230
>> | [...]
>> | + used linklint to verify links in the HTML documentation, made fixes
>> | to manpages as needed.
>> `----
>>
>> That change fixed the links in the HTML documentation, but broke the
>> references in the manpages themselves.
There have been more of such issues, for instance #1004901 and #1057651.
However, thanks to Branden Robinson's work on the manpages in recent
months, all but one reference should be fixed in the latest patchlevel.
I just sent a patch upstream for the last one[4].
> The html documentation _could_ be generated to be consistent with the
> manpages, but that would complicate the Debian package...
Apparently we would need to package or vendor your version of man2html
and run it with suitable options on the installed manpages. There does
not seem to be a dedicated target in the Makefiles to regenerate the
HTML documentation, if I understand correctly this is done as part of
"make dist".
Certainly that is not impossible, but it is also something I am not
exactly keen on.
Cheers,
Sven
1. https://lists.debian.org/debian-devel/1996/06/threads.html#00281
2. https://lists.debian.org/debian-devel/1996/06/msg00364.html
3. https://lists.debian.org/debian-devel/1996/06/msg00393.html
4. https://lists.gnu.org/archive/html/bug-ncurses/2024-01/msg00001.html
