discuss: Man pages converted to HTML
Subject:
Re: [discuss] Man pages converted to HTML
From:
David Lawyer ####@####.####
Date:
30 May 2007 22:05:32 -0000
Message-Id: <20070530220545.GB1992@davespc>
> >On Mon, May 28, 2007 at 09:28:26AM -0400, Sam Varshavchik wrote:
> >>My HTML compilation includes not just LDP's man pages, but they also
> >
> David Lawyer writes:
> >I'd like to see the whole multi-sourced collection available on LDP
> >but we are short of volunteers so if you are willing, perhaps you
> >could be given write access to the part of the ldp site that would
> >contain the man pages in both html and groff, etc. This likely would
> >be the page (and directory tree) you get to by selecting "man pages"
> >on LDP's homepage. Thus you would be the LDP volunteer maintaining
> >LDP's expanded distribution of man pages, but not actually maintaining
> >any particular man-page (unless there is to be a man page telling
> >people about the availability of html man-pages).
>
On Tue, May 29, 2007 at 07:04:52AM -0400, Sam Varshavchik wrote:
> Well, the way that I did the conversion was not to merge multiple man page
> sources together into one set, then crunch the whole thing through the
> htmlizer. I do not really have a consolidated tarball of man pages in the
> original troff source, that I assemble from multiple sources. I try to
> maintain my stuff so that it's easy to refresh the HTML against newer
> releases of the upstream source. All man page sources are kept in separate
> directories, and the conversion script just goes through and picks up the
> original troff source from each directory.
This is OK since most people get the troff source with their
distribution. But if the troff source is to be stored at LDP it
should only be at the main site and not at the LDP mirrors.
>
> >Perhaps the other stuff referenced on the page you get to by clicking
> >"man-page" should be put into another directory also referenced from
> >the homepage --or what amounts to the same thing: create a new
> >directory for only man-pages.
The above paragraph hasn't been responded to yet.)
>
> I would suggest an approach of just citing the link to the original FTP
> site, and instead of keeping a copy of MTK's tarballs on tldp.org, host the
> consolidated HTML tarball.
Right now it's not only at the LDP master site but also at all the
mirrors. Since distributions should include this LDP only needs a
link to it as you suggest above.
I should say that, IMHO, troff is long overdue
> for retirement. I'd rather see some advocacy for wide adoption and
> migration to more modern documentation formats, such as HTML, or
> Docbook XML. What do others think of this idea: rather just hosting
> a copy of man page troff source, describe LDP's man page section as
> offering HTML versions of man pages, and just point people to where
> they can get the original troff source?
Good idea. Regarding the format for man-pages, I think that html
generated from LinuxDoc (SGML) source would be a good solution since
it's easy to create a doc in LinuxDoc. The LinuxDoc source would not
be distributed with distributions (except in source packages). There
would also be a plain-text version which would be generated from the
LinuxDoc source, which by the way, uses troff internally to create
text output (so troff is still needed).
> I'll be happy to volunteer to maintain this, and I'll continue to
> run the browsable version.
The LDP site(s) should also have a browsable version. Should the
mirrors also get the browsable version? They now have browsable
versions of all the HOWTOs. Will the man pages be read online as much
as the HOWTOs? Probably not, since almost all distributions
distribute the man pages; but not so for the HOWTOs. But if there is a
big demand for the man pages, then they belong on the mirrors to
reduce load on the LDP master site.
> They're indexed by Google, so searching the man pages is now very,
> very useful. Type "signal" into the search box, and you'll get
> links to both signal(2) and signal(7), as well as a bunch of related
> syscalls (kill, wait, etc???)
>
> Can't beat that.
On a standard installation (troff), typing man -k signal finds a lot
more results. But there are no links to click on so you have to type
"man ..." again to follow "links".
David Lawyer
