Wiki bug: Documentation_Index generated wrongly

[Jakob Bohm]

The code/script which generates
http://wiki.openssl.org/index.php/Documentation_Index
from the manpages looks like it contains two bugs:

1. If a manpage lists another function under "see also", that other
function is listed as a subitem of that first manpage, causing
lotsof duplicate entries in the list.

2. If a function is listed in the NAME section of a manpage (as it
should), but not in any "see also" of other manpages, it is not
listed at all. This affects functions such as SSL_set_mode(),
because all the other manpages only does a see also for the
combined SSL_CTX_set_mode() and SSL_set_mode() manpage.

In other words, the script looks like it is indexing the SEE ALSO
section, ratherthan the TITLES and NAME sections (which is what
man(1) on *n*x does).

Enjoy

Jakob
--
Jakob Bohm, CIO, Partner, WiseMo A/S. http://www.wisemo.com
Transformervej 29, 2860 Søborg, Denmark. Direct [phone]
This public discussion message is non-binding and may contain errors.
WiseMo - Remote Service Management for PCs, Phones and Embedded

______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List openssl-users-MCmKBN63+***@public.gmane.org
Automated List Manager majordomo-MCmKBN63+***@public.gmane.org

[Matt Caswell]

Post by Jakob Bohm
The code/script which generates
http://wiki.openssl.org/index.php/Documentation_Index
1. If a manpage lists another function under "see also", that other
function is listed as a subitem of that first manpage, causing
lotsof duplicate entries in the list.
2. If a function is listed in the NAME section of a manpage (as it
should), but not in any "see also" of other manpages, it is not
listed at all. This affects functions such as SSL_set_mode(),
because all the other manpages only does a see also for the
combined SSL_CTX_set_mode() and SSL_set_mode() manpage.
In other words, the script looks like it is indexing the SEE ALSO
section, ratherthan the TITLES and NAME sections (which is what
man(1) on *n*x does).

Hi Jakob

Yeah....the "script" was a one off hack that I did, munging stuff
through a series of command line tools to come up with something
vaguely useful :-) It needs industrialising....and re-running.

With regards to the "bugs":
1) The idea was that you could find a mention of a function anywhere
in the man pages...whether it was the primary man page for that
function or not. IIRC I scanned the header files and pulled out a list
of functions, and then looked for references to those functions
anywhere in the man pages. If it found a match it put an entry in the
index. So the duplicate entries, was by design (although perhaps not
very "pretty" :-) ). The links in bold are intended to be the primary
source of information for that function....i.e. the man page with the
function listed under the NAME section.

2) I don't think that is actually what is going on. E.g see
PEM_write_X509_CRL, which does seem to be correctly listed but only
appears on one page. I suspect if a function is not listed at all then
it probably means one of:
a) My script for pulling out the function names from the header files
is broken (it was just a hack)
b) A man page has been updated since I ran the scripts (at one point
there were quite a few errors in the NAME section across a number of
man pages, which I tidied up...can't remember if that was before or
after I generated the index)

Anyway, I haven't done anything with the index for a while because it
seemed to pass by unnoticed and I wasn't sure whether people were
actually using it. If people think its useful, I'll see if I can spend
some time to get it working properly.

Matt
______________________________________________________________________
OpenSSL Project http://www.openssl.org
User Support Mailing List openssl-users-MCmKBN63+***@public.gmane.org
Automated List Manager majordomo-MCmKBN63+***@public.gmane.org