On Tue, Mar 07, 2006 at 04:20:16PM +1100, Damien Miller wrote:
> On Sun, 5 Mar 2006, Kurt Roeckx wrote:
>
> > Hi,
> >
> > I would like to properly place the documetation in the 1SSL,
> > 3SSL, 5SSL and 7SSL section.
>
> It might be proper for your operating system, but it certainly
> isn't correct for everyone. None of the operating systems I have
> at hand even have a 3ssl section.
It's not because you don't have a 3ssl section that your OS
doesn't support this. Typical examples on my Linux system
include X, which are in section 3X, like for instance
XrmInitialize().
I can get that manpage with "man 3x XrmInitialize", but
"man 3 XrmInitialize" works just as well. That manpage is stored
in: /usr/X11R6/man/man3/XrmInitialize.3x.gz
Other typical examples include manpages from ncurses, which are
in section 3ncurses for me.
On my Solaris, the printf() functions for instance is in section
3s, not in section 3.
oink% man -s 3 printf
No entry for printf in section(s) 3 of the manual.
oink% man -s 3s printf
Reformatting page. Wait... done
Standard I/O Functions printf(3S)
Where that file is then /usr/share/man/man3s/printf.3s
This atleast shows that setting MANSUFFIX doesn't work there as
expected.
I don't have access to a any of the *BSD's, but FreeBSD also
seems to use it, and documents that the .TH macro can take an
extention.
Note that pod2man's --section only has as effect that the
section in the .TH macro is changed, which seems to be
working on all versions I can think off.
We still need to place the file in the right place, which
seems to depend on the OS, where it seems for most the
path would include the full section, while on Linux only
the number.
So, it seems that the MANSUFFIX change in my patch should
be undone for most OS, except for Linux, and have
something that still works. The MANSUFFIX handling should
depend on the OS.
> So unconditionally changing it will break things for many (most?)
> people. Perhaps you could make this a platform-specific change and
> do the subsitiutions in the pod files based on the OS?
I think the only problem is getting the path right
depending on the OS, as explained above.
Anyway, I've attached a patch that should have as effect
that there is no change at all, except that the pod files
are changed. But the resulting manpage shouldn't change.
I think changing the pod files is going to make it easier
to actually do the substitutions, the other way around is
going to be hard.
So, what do you think about the attached change the
Makefile.org, with the changes to the pod file from my
previous patch?
Kurt
Index: Makefile.org
===================================================================
RCS file: /home/kurt/openssl/cvs/openssl-cvs/openssl/Makefile.org,v
retrieving revision 1.272
diff -u -r1.272 Makefile.org
--- Makefile.org 12 Feb 2006 23:11:18 -0000 1.272
+++ Makefile.org 7 Mar 2006 19:54:04 -0000
@@ -130,6 +130,7 @@
MAN1=1
MAN3=3
MANSUFFIX=
+MANSECTION=
SHELL=/bin/sh
TOP= .
@@ -557,9 +558,10 @@
sec=`$(PERL) util/extract-section.pl 1 < $$i`; \
echo "installing man$$sec/$$fn.$${sec}$(MANSUFFIX)"; \
(cd `$(PERL) util/dirname.pl $$i`; \
- sh -c "$$pod2man \
- --section=$$sec --center=OpenSSL \
- --release=$(VERSION) `basename $$i`") \
+ sh -c "sed -e 's/(\([1-9]\)SSL)/(\1$(MANSECTION))/g' \
+ `basename $$i` | $$pod2man \
+ --section=$${sec}$(MANSECTION) --center=OpenSSL \
+ --release=$(VERSION)") \
>
$(INSTALL_PREFIX)$(MANDIR)/man$$sec/$$fn.$${sec}$(MANSUFFIX); \
$(PERL) util/extract-names.pl < $$i | \
(grep -v $$filecase "^$$fn\$$"; true) | \
@@ -574,9 +576,10 @@
sec=`$(PERL) util/extract-section.pl 3 < $$i`; \
echo "installing man$$sec/$$fn.$${sec}$(MANSUFFIX)"; \
(cd `$(PERL) util/dirname.pl $$i`; \
- sh -c "$$pod2man \
- --section=$$sec --center=OpenSSL \
- --release=$(VERSION) `basename $$i`") \
+ sh -c "sed -e 's/(\([1-9]\)SSL)/(\1$(MANSECTION))/g' \
+ `basename $$i` | $$pod2man \
+ --section=$${sec}$(MANSECTION) --center=OpenSSL \
+ --release=$(VERSION)") \
>
$(INSTALL_PREFIX)$(MANDIR)/man$$sec/$$fn.$${sec}$(MANSUFFIX); \
$(PERL) util/extract-names.pl < $$i | \
(grep -v $$filecase "^$$fn\$$"; true) | \
