[darcs-users] Review: improve front page of http://darcs.net

Trent W. Buck trentbuck at gmail.com
Fri Oct 31 00:18:30 UTC 2008


On Thu, Oct 30, 2008 at 03:39:57PM -0500, Eric P. Mangold wrote:
> On Wed, Oct 29, 2008 at 9:43 PM, Trent W. Buck <trentbuck at gmail.com> wrote:
> > Eric P. Mangold <teratorn at gmail.com> writes:
> [...]
> >> ] hunk ./doc/index.html.in 53
> >>            <h2>Smart</h2>
> >>
> >>            <p>Originally developed by physicist David Roundy, darcs is
> >> -          based on a unique algebra of patches. </p>
> >> +          based on a unique <a href="manual/node9.html">algebra of patches.</a></p>
> >
> > This part sounds fine, as long as we're OK with referring to a page in
> > the manual by number.  I'm a bit nervous about that, because rearranging
> > the manual could cause node9 to become node3 or node12.  Is there a
> > related article on the wiki which could be linked to instead?  Wiki
> > articles have semantic names and are thus less likely to change.
> 
> There doesn't seem to be anything on the wiki that should be used in
> this case.

OK, then I agree with adding the link as-is; we can reexamine this
once we transition to reST.

> Being unable to cleanly link to pages in the manual is pretty crummy.

I agree.

> I had a look through the darcs source tree but I couldn't figure out
> how the HTML is generated(?)

This is something I'm hoping to address with my make and user-manual
patch bundles.  Currently, the flow look like this:


    src/darcs.lhs (and recursively, other .lhs and .tex files)
        |
        |   preproc (src/preproc/.hs)
        V
    src/darcs*.tex
        |
        |   latex2html (or tex4ht)
        V
    doc/manual/*.html

> Perhaps there is some way to switch it to use names instead of
> numbers, or perhaps some way to automatically produce a set of
> "named" pages that redirect to their "numbered" counterparts.

This will be resolved as a side-effect of switching to reST.  The
default single-page style will give "darcs.html#patch-theory", i.e. a
semantic anchor name.  We hope also to have split-file HTML output,
which will give us "patch-theory.html".


More information about the darcs-users mailing list