On Wed, Jan 24, 2007, Jeff Smith wrote about "Re: Manual Pages":
> First of all, you said "someone *already* wrote such manual pages",
> but then you point to HTML pages. Do you not understand the
> difference between "man" and "HTML"?
Surely I understand... I've been using manual pages for 22 years, and HTML
for 13 years. There's no need to assume that I don't know what I'm talking
about :-)
What I said was that these HTML pages (which are ultimately generated from
docbook sources) contain exactly the kind of text that users expect
to find in a manpage, with exactly the sections that are expected. I never
tried to claim that these pages use Troff's "an" macros, or anything like
that.
> Ok I don't seriously think that
> nobody has made it into man page format, yet why would the subversion
> team need to maintain man page format when they already have
> automatically generating HTML help (which is ultimately better)?
Each of the documentations formats and styles you mentioned have their
advantages and disavantages, and we can debated them ad nauseam (I already
mentioned some of the man advantages in previous posts).
The point was that nobody needs to "maintain man page format" - I wanted it
to be completely automatic - just like the HTML and PDF gets created
automatically from the docbook sources, so can the man pages.
The big win would be that Unix/Linux users, which traditionally find these
manpages useful, will have them. I never tried to suggest that we should
drop the HTML pages.
> Further, you will find that for 10 years authors have been
> deprecating their `man` pages and generating more manageable formats,
> like `info`.
This debate is far from clear-cut. There are advantages to both styles
(these are not just file formats!) of documentation. Texinfo documentation
is best for long, book-like, with many sections, subsections, introduction,
and so on. Man pages are short references only for *shell commands* and
*C APIs* (for other things, like GUI programs, man pages won't work well,
and you must use something like texinfo or HTML). So each is appropriate for
different things.
The beautiful thing about the svnbook is that it already contains both
styles of documentation - it starts with a long detailed tutorial (of the
kind that sometimes appear in texinfo documentation), and ends with a
short but accurate reference for each of the shell commands - exactly of
the type that is normally found in man pages.
> Now I see that you are not even requesting to build "man" pages (after
> all, they wouldn't even work in MS Win). You are only saying that you
> don't think the docs are complete, or consolidated enough.
No way! That's not what I said! I think they are very complete, and just
wished that the sections which already look like man pages, could be made
into actual man pages which I could fetch with the "man" command, instead
of going through HTML links.
--
Nadav Har'El | Wednesday, Jan 24 2007, 5 Shevat 5767
nyh@math.technion.ac.il |-----------------------------------------
Phone +972-523-790466, ICQ 13349191 |Schroedinger's cat has 18 half-lives.
http://nadav.harel.org.il |
---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@subversion.tigris.org
For additional commands, e-mail: users-help@subversion.tigris.org
Received on Wed Jan 24 16:41:44 2007