Vastly better HTML docs

Vastly better HTML docs

[Jesse W]

I've (finally) figured out how to generate a HTML version of the zsh 
docs with sane and helpful file and anchor names.   And it's really 
easy.

The HTML version of the zsh docs are generated from the texinfo version 
by a program called texi2html.  The version that is currently being 
used to generate the online copy of the docs is 1.64, which was 
released in 2000 (!) and whose maintainer hasn't released a new version 
since.  However, the project has been taken up by another maintainer, 
who has put out more recent releases, (available from 
http://www.nongnu.org/texi2html/ ), with some extremely nice features.

If you generate the zsh docs with the current version (1.82), and use 
the --node-files option, it will make html files with *actual* 
*descriptive* *names* (like "Shell-Grammar.html", or 
"Editor-Functions-Index.html").

**EVEN BETTER**, the index anchors, which in the current version are 
opaque, unguessable numerical codes, are now self-evident, easily 
guess-able links like "#index-compadd" or 
"#index-background-jobs_002c-notification" (_002c is a comma -- maybe 
not totally obvious, but understandable once seen).

Combining these, you get the very automatable, human-readable URLs 
like: "Options.html#index-EQUALS" for the EQUALS option, etc.

And the whole things is very customizable, so if we want to change it 
(maybe making underscores, which currently show up as "_005f", 
something simpler), we can do so easily...

It would be great to get these improved URLs live on the various zsh 
doc mirrors, so we can start linking to them from the wiki, and other 
places.

Let me know how else I can help with this,

Jesse Weinstein

Re: Vastly better HTML docs

[Peter Stephenson]

On Tue, 14 Apr 2009 02:19:54 -0700
Jesse W <jessw@netwood.net> wrote:
> If you generate the zsh docs with the current version (1.82), and use 
> the --node-files option, it will make html files with *actual* 
> *descriptive* *names* (like "Shell-Grammar.html", or 
> "Editor-Functions-Index.html").

The version being distributed on the systems I have is actually 1.78.

This turns the option on.  We now have to assume all .html options are
output from texi2html, but it's a good bet.

Index: Doc/.cvsignore
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/.cvsignore,v
retrieving revision 1.5
diff -u -r1.5 .cvsignore
--- Doc/.cvsignore	25 Oct 2006 09:46:45 -0000	1.5
+++ Doc/.cvsignore	16 Apr 2009 10:09:51 -0000
@@ -3,7 +3,7 @@
 zsh*.1
 zsh.texi
 zsh.info*
-zsh*.html
+*.html
 zsh.aux zsh.toc
 zsh.cp zsh.cps
 zsh.fn zsh.fns
Index: Doc/.distfiles
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/.distfiles,v
retrieving revision 1.9
diff -u -r1.9 .distfiles
--- Doc/.distfiles	26 Nov 2007 09:58:59 -0000	1.9
+++ Doc/.distfiles	16 Apr 2009 10:09:51 -0000
@@ -15,7 +15,7 @@
 
 DISTFILES_DOC='
     zsh.info zsh.info-[0-9]*
-    zsh.html zsh_*toc.html zsh_[0-9]*.html
+    *.html
     zsh.dvi
     zsh.pdf
 '
Index: Doc/Makefile.in
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Makefile.in,v
retrieving revision 1.44
diff -u -r1.44 Makefile.in
--- Doc/Makefile.in	3 Mar 2009 15:04:27 -0000	1.44
+++ Doc/Makefile.in	16 Apr 2009 10:09:51 -0000
@@ -40,7 +40,7 @@
 MAKEINFO = makeinfo
 TEXI2DVI = texi2dvi
 DVIPS = dvips
-TEXI2HTML = texi2html --output . --ifinfo --split=chapter
+TEXI2HTML = texi2html --output . --ifinfo --split=chapter --node-files
 
 .SUFFIXES: .yo .1
 
-- 
Peter Stephenson <pws@csr.com>                  Software Engineer
CSR PLC, Churchill House, Cambridge Business Park, Cowley Road
Cambridge, CB4 0WZ, UK                          Tel: +44 (0)1223 692070

Re: Vastly better HTML docs

[Jesse W]

On Apr 16, 2009, at 3:11 AM, Peter Stephenson wrote:
> The version being distributed on the systems I have is actually 1.78.
Looking over the NEWS files, it looks like the important new features 
are present in that version, so that'll still work.
> This turns the option on.
Great.  When can I expect a new version to be uploaded to 
zsh.docsrc.org and zsh.sourceforge.net, and is this anything I can be 
of help with?
> We now have to assume all .html options are
> output from texi2html, but it's a good bet.
We could also add the zsh- prefix to all the generated file names 
easily enough, if that would make things safer...

Here's a patch to the documentation where we mention the details of the 
HTML conversion (do we really need this? Maybe we should just change it 
to "Please look in the Makefile". ;-))

Index: manual.yo
===================================================================
RCS file: /cvsroot/zsh/zsh/Doc/Zsh/manual.yo,v
retrieving revision 1.18
diff -u -r1.18 manual.yo
--- manual.yo   14 Jul 2008 17:39:26 -0000      1.18
+++ manual.yo   16 Apr 2009 18:28:14 -0000
@@ -187,9 +187,9 @@
  tt(http://zsh.sunsite.dk/Doc/).

  (The HTML version is produced with bf(texi2html), which may be obtained
-from tt(http://www.mathematik.uni-kl.de/~obachman/Texi2html/). The 
command is
-`tt(texi2html -split chapter -expand info zsh.texi)'.  If necessary,
-upgrade to version 1.64 of texi2html.)
+from tt(http://www.nongnu.org/texi2html/). The command is
+`tt(texi2html --output . --ifinfo --split=chapter --node-files 
zsh.texi)'.  If necessary,
+upgrade to version 1.78 of texi2html.)
  )
  enditem()

Re: Vastly better HTML docs

[Richard Hartmann]

On Tue, Apr 14, 2009 at 11:19, Jesse W <jessw@netwood.net> wrote:

> I've (finally) figured out how to generate a HTML version of the zsh docs
> with sane and helpful file and anchor names.   And it's really easy.

Will the old links still work? Else, links to the docs from the outside will
break.


Richard

Re: Vastly better HTML docs

[Peter Stephenson]

Richard Hartmann wrote:
> On Tue, Apr 14, 2009 at 11:19, Jesse W <jessw@netwood.net> wrote:
> 
> > I've (finally) figured out how to generate a HTML version of the zsh docs
> > with sane and helpful file and anchor names. And it's really easy.
> 
> Will the old links still work? Else, links to the docs from the outside will
> break.

The top-level links are the same, i.e. table of contents etc.  The inner
links were a moving target anyway---they wouldn't stay the same if the
docs were updated, as they occasionally were (they should be update more
frequently, but it's hard to get volunteers), which was part of the
problem.

-- 
Peter Stephenson <pws@csr.com>                  Software Engineer
CSR PLC, Churchill House, Cambridge Business Park, Cowley Road
Cambridge, CB4 0WZ, UK                          Tel: +44 (0)1223 692070

Re: Vastly better HTML docs

[Peter Stephenson]

On Thu, 16 Apr 2009 11:33:13 -0700
Jesse W <jessw@netwood.net> wrote:
> > This turns the option on.
> Great.  When can I expect a new version to be uploaded to 
> zsh.docsrc.org and zsh.sourceforge.net, and is this anything I can be 
> of help with?

I know nothing about zsh.docsrc.org, but I think the sourceforge pages
you're talking about are mirrors of the ones at zsh.sunsite.dk; I don't
know whether mirroring is automated.  I don't know who, if any, thinks
they're in charge of updating the ones at sunsite.dk at the moment.  Maybe
they'll own up.

-- 
Peter Stephenson <pws@csr.com>                  Software Engineer
CSR PLC, Churchill House, Cambridge Business Park, Cowley Road
Cambridge, CB4 0WZ, UK                          Tel: +44 (0)1223 692070

Re: Vastly better HTML docs

[Richard Hartmann]

On Fri, Apr 17, 2009 at 15:20, Peter Stephenson <pws@csr.com> wrote:

> I know nothing about zsh.docsrc.org, but I think the sourceforge pages
> you're talking about are mirrors of the ones at zsh.sunsite.dk; I don't
> know whether mirroring is automated.  I don't know who, if any, thinks
> they're in charge of updating the ones at sunsite.dk at the moment.  Maybe
> they'll own up.

It seems sunsite.dk has been transformed into dotsrc.org. Thankfully, they
left their subdomains intact ;)

If no one from there shows up, I can write to staff@dotsrc.org if you want
me to.


Richard

Re: Vastly better HTML docs

[Jesse W]

Regarding breaking links -- there is another option to texi2html, 
--use-nodes, which will create redirects from all the node names to the 
chapter pages.  I'm not sure if this will make things worse or better.  
We could also generate redirects with the old-style names, with pretty 
little trouble, I think.  But Peter is right, the old names weren't 
exactly persistent, either.

On Apr 17, 2009, at 6:55 AM, Richard Hartmann wrote:
> It seems sunsite.dk has been transformed into dotsrc.org. Thankfully, 
> they
> left their subdomains intact ;)
>
> If no one from there shows up, I can write to staff@dotsrc.org if you 
> want
> me to.
That would be very appreciated (by me, if no one else. ;-) )  If you 
can find an email for the sourceforge people, that would be great too.

Jesse Weinstein

Re: Vastly better HTML docs

[Peter Stephenson]

On Sat, 18 Apr 2009 11:23:41 -0700
Jesse W <jessw@netwood.net> wrote:
> On Apr 17, 2009, at 6:55 AM, Richard Hartmann wrote:
> > It seems sunsite.dk has been transformed into dotsrc.org. Thankfully, 
> > they
> > left their subdomains intact ;)
> >
> > If no one from there shows up, I can write to staff@dotsrc.org if you 
> > want
> > me to.
> That would be very appreciated (by me, if no one else. ;-) )  If you 
> can find an email for the sourceforge people, that would be great too.

zsh@dotsrc.org, assuming that's what it's now called (was
zsh@sunsite.dk), would be more useful, but the question is who is
actually doing the work on the zsh side, not who has permission to
access it.  However, if you have some time to spare, do volunteer to be
added...  You might need to copy both addresses, I've rather lost track
of what's going on.

-- 
Peter Stephenson <p.w.stephenson@ntlworld.com>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/

Re: Vastly better HTML docs

[Richard Hartmann]

On Sat, Apr 18, 2009 at 20:49, Peter Stephenson
<p.w.stephenson@ntlworld.com> wrote:

> zsh@dotsrc.org, assuming that's what it's now called (was
> zsh@sunsite.dk), would be more useful, but the question is who is
> actually doing the work on the zsh side, not who has permission to
> access it.  However, if you have some time to spare, do volunteer to be
> added...  You might need to copy both addresses, I've rather lost track
> of what's going on.

I had a pretty massive weekend and start of week, but I will poke them
about what to do :)


Richard

Re: Vastly better HTML docs

[Richard Hartmann]

On Tue, Apr 21, 2009 at 12:09, Richard Hartmann
<richih.mailinglist@gmail.com> wrote:

> I had a pretty massive weekend and start of week, but I will poke them
> about what to do :)

Other than a ticket number (22123), I never received a reply to this. I poked
them again and will try to find someting.


RIchard

Re: Vastly better HTML docs

[Jesse W]

On May 27, 2009, at 9:39 AM, Richard Hartmann wrote:
> On Tue, Apr 21, 2009 at 12:09, Richard Hartmann
> Other than a ticket number (22123), I never received a reply to this. 
> I poked
> them again and will try to find someting.
Thanks.

The sf.net project lists Bart, Peter, and Oliver Kiddle as project 
admins -- if we can't reach the folks at sunsite.dk, maybe one of them 
could just upload current documentation to sf.net?

Jesse Weinstein

Re: Vastly better HTML docs

[Peter Stephenson]

On Wed, 27 May 2009 16:59:01 -0700
Jesse W <jessw@netwood.net> wrote:
> On May 27, 2009, at 9:39 AM, Richard Hartmann wrote:
> > On Tue, Apr 21, 2009 at 12:09, Richard Hartmann
> > Other than a ticket number (22123), I never received a reply to this. 
> > I poked
> > them again and will try to find someting.
> Thanks.
> 
> The sf.net project lists Bart, Peter, and Oliver Kiddle as project 
> admins -- if we can't reach the folks at sunsite.dk, maybe one of them 
> could just upload current documentation to sf.net?

I will update the manual when 4.3.10 appears.

-- 
Peter Stephenson <p.w.stephenson@ntlworld.com>
Web page now at http://homepage.ntlworld.com/p.w.stephenson/

Re: Vastly better HTML docs

[Oliver Kiddle]

Jesse W wrote:
> The sf.net project lists Bart, Peter, and Oliver Kiddle as project 
> admins -- if we can't reach the folks at sunsite.dk, maybe one of them 
> could just upload current documentation to sf.net?

I have just uploaded new docs (before seeing Peter's recent message).
I've not got a TeX installation so haven't bothered with the PDF, ps
and dvi files.

These are only at sunsite.dk/dotsrc.org. Sourceforge has changed things
around a lot and you have to jump through hoops just to ssh in and then
it can't rsync the stuff anyway (failed to connect to zsh.sunsite.dk:
No route to host (113)). If anyone wants to try, the appropriate command
is: rsync -aqz zsh.sunsite.dk::zsh /home/groups/z/zs/zsh/htdocs
Probably need to sftp it up instead.

If anyone with more time than me wants to do some work on the zsh web
pages, I'll be happy to upload them assuming we can't find someone at
sunsite.dk to add them.

Oliver

Re: Vastly better HTML docs

[Jesse W]

On May 28, 2009, at 1:03 PM, Oliver Kiddle wrote:
> Jesse W wrote:
> I have just uploaded new docs (before seeing Peter's recent message).
Thank you, thank you, thank you!
> I've not got a TeX installation so haven't bothered with the PDF, ps
> and dvi files.
I'll generate those formats, and send you a link to a tarball of them 
for uploading.

> These are only at sunsite.dk/dotsrc.org. Sourceforge has changed things
> around a lot and you have to jump through hoops just to ssh in and then
> it can't rsync the stuff anyway (failed to connect to zsh.sunsite.dk:
> No route to host (113)). If anyone wants to try, the appropriate 
> command
> is: rsync -aqz zsh.sunsite.dk::zsh /home/groups/z/zs/zsh/htdocs
Ick.  Sorry (but not that surprised) to hear that.  Hopefully we'll get 
it sorted.
> Probably need to sftp it up instead.

There's one problem with the HTML docs, though -- while they now have 
good, transparent names, the internal anchors are still opaque 
numerical forms.  I'll regenerate the docs locally, and see what might 
have happened.  And I'll include the HTML in the tarball, so you can 
use my version if it's not working to generate it yourself.

Thanks again for uploading the new version (and thanks in advance for 
uploading the corrected one ;-) )

Jesse Weinstein