man page situation [u]

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

man page situation [u]

Andreas Jellinghaus-2
Hi Bert,

I'm not sure what the current situation with the man pages
is. Shall I remove the *.3 man pages (in docs / now in man)
in favour of your new api documentation?

Also could you tell me more about the xml format you are
using and the style sheets. Do you think we should convert
the tools and config file man pages to that toolchain, too?

So far I changed the makefiles so the next release tar file
will include your xml files, but I'm not sure if we should
include them as html and man, too, and whether they are ready
to replace the older manualy written man pages.

Regards, Andreas
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
Reply | Threaded
Open this post in threaded view
|

Re: man page situation [u]

Bert Vermeulen
Andreas Jellinghaus [c] wrote:

> I'm not sure what the current situation with the man pages
> is. Shall I remove the *.3 man pages (in docs / now in man)
> in favour of your new api documentation?

Yes (but it looks like you already did). The .3 manpages were converted
a long time ago, and a lot more created. The tool manpages (.1) were
not, but I've since done a bunch of those as well. However I forgot to
check them into the subversion repository :-)
I'll do that shortly.

> Also could you tell me more about the xml format you are
> using and the style sheets.

It's basically standard docbook 4.2. There's a lot of room for
improvization in that, however, since it's a huge and flexible format.
Basically I've used whatever I needed until it looked right after
conversion to HTML and manpage format with the tools I use.

As for the toolset, you need two things:

- xsltproc, comes with libxslt (http://xmlsoft.org/XSLT/)

- the docbook XSL stylesheets are used for both HTML and manpage
   output, see http://docbook.sourceforge.net/projects/xsl/

I had a Makefile in the toplevel doc/ directory, but it looks like that
just got overwritten by that wiki dump. Could you maybe make a separate
directory for those wiki HTML files and associated Makefile? It's a but
cluttered right now, and the Makefile is important.

 > Do you think we should convert the tools and config file man pages
 > to that toolchain, too?

Yes, absolutely. The whole thing is very easy to use, and given the
right stylesheet, can convert the documentation to anything.

> So far I changed the makefiles so the next release tar file
> will include your xml files, but I'm not sure if we should
> include them as html and man, too, and whether they are ready
> to replace the older manualy written man pages.

They're fine to replace the old manpages. As to whether to include
converted output, I would say that's a release manager's decision. Not
everybody will have xsltproc and those docbook stylesheets handy, so the
decision is really whether you want to make that a requirement for
people who want the docs.

However, I would ask that you keep HTML and manpage output out of the
subversion repository, since that will just cause problems (people will
change those instead of the XML source, etc).


Bert Vermeulen
[hidden email]
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
Reply | Threaded
Open this post in threaded view
|

Re: man page situation [u]

Andreas Jellinghaus-2
Hi Bert,

thanks for your feedback.

btw: I only moved your makefile one level down to
src/, changed it to automake format, and
- temporary - disabled the macros to generate html/man.

if noone objects, I will add a shell script to generate
man and html pages (meant to be run only by developers
and only if they want, not everytime you type "make").
tar.gz files will then include xml, html and man format.

Regards, Andreas
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
Reply | Threaded
Open this post in threaded view
|

Re: Re: man page situation

Andreas Jellinghaus-2
In reply to this post by Bert Vermeulen
Hi,

the man page topic was sleeping for a while, but
now I'd like to continue to work on it.

If noone objects I will remove the man/* man pages
and put the new xml based man paged by bert in place.

Regards, Andreas
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel
Reply | Threaded
Open this post in threaded view
|

Re: Re: man page situation

Andreas Jellinghaus-2
btw. the man page situation is a bit tricky:
like all documentation I don't want to build
it during "make" but only with "make dist".

but man pages should be installed with "make install".

So my plan is this: "make dist" will generate the
man pages and place them in $(top)/man/.
"make install" will install those man pages, if
there are any.

so for a normal user:
tar xfvz ...; configure ; make; make install
is fine because the tar file contains the man
pages in xml, html and man format.

but for developers using svn it will be a bit
strange:
svn co ... ; bootstrap; configure; make; make install
will not install many man pages, as there are none
in man format in the svn.

an additional "make dist; make install" will do
the trick, make dist will generate them, make
install then install them.

is this ok with everyone?

Andreas
p.s. also I have to think about what to do with
pkcs15-profile.xml.in / we can't use configure
to change some directory value in the man/xml/...
file. I think I simply remove that, and mention
the default and config file.
_______________________________________________
opensc-devel mailing list
[hidden email]
http://www.opensc.org/cgi-bin/mailman/listinfo/opensc-devel