Hello,
I have two suggestions about the documentation.
First suggestion, a minor one about INSTALL.W32. Every time I go to
change ./ms/do_ms.bat so I can enable debugging symbols I change the
line
perl util\mk1mf.pl no-asm VC-WIN32 >ms\nt.mak
I add 'debug' in last place after all the other options, after
'VC-WIN32'. This means, of course, the ms/nt.mak ends up being the
makefile for a un*x debug build and thus nmake barfs.
Perhaps in the "Tweaks" section, which starts at line 80, it could be
changed from saying "If you add 'debug' to the mk1mf.pl lines in the
do_* batch file then debugging symbols will be compiled in" to
something specific that says the 'debug' needs to be added _before_ the
architecture specification. So the person will have
perl util\mk1mf.pl no-asm debug VC-WIN32 >ms\nt.mak
rather than
perl util\mk1mf.pl no-asm VC-WIN32 debug >ms\nt.mak
where VC-WIN32 could also be VC-MSDOS or VC-W31-32.
Does this sound good? I hope I'm not just a stupid putz who is the only
person to have made this mistake. :-)
Second suggestion is about the *.pod docs files, which I've already
mentioned over on openssl-users, but I thought it might be good to
specifically say it here, too.
The L<> pod-links in the current *.pod docs all appear to be like this:
L<SSL_accept(3)|SSL_accept(3)> with the part after the | exactly the
same as the part before. When I run my pod2html (ActivePerl on
Win2Kpro) to make *.html docs, it barfs on any of the pod-links unless
the part after the | can be found in that same pod file. The result is
that pod-links where the text doesn't appear previously, like
L<openssl(1)|openssl(1)> end up being merely italicized in the HTML
version rather than a bona fide hyperlink to something like
../apps/openssl.html. And text that does appear, like
L<SSL_accept(3)|SSL_accept(3)> become a link back to a <a
name="whatever"></a> in the same page rather than a hyperlink to
../ssl/SSL_accept.html (the HTML-ized version of
doc/ssl/SSL_accept.pod).
If I understand things correctly, L<SSL_accept(3)|SSL_accept(3)> could
be changed to L<SSL_accept(3)|SSL_accept> (along with all other L<>
pod-links as well) _without_ affecting the output of pod2man in any way
so make install_docs still works on un*x systems. At the same time
pod2html can now be run without barfing to produce properly hyperlinked
HTML docs for systems which don't have man, like Windows.
Have I missed anything or would this change really work? If it would
work, I'd be more than willing to make the changes to all the *.pod
docs if somebody would just point me in the direction of official
procedures for submitting the changes.
--
__________________________________________________
Do you Yahoo!?
New DSL Internet Access from SBC & Yahoo!
http://sbc.yahoo.com
______________________________________________________________________
OpenSSL Project http://www.openssl.org
Development Mailing List [EMAIL PROTECTED]
Automated List Manager [EMAIL PROTECTED]
______________________________________________________________________
OpenSSL Project http://www.openssl.org
Development Mailing List [EMAIL PROTECTED]
Automated List Manager [EMAIL PROTECTED]
