Re: new tool for website -- versioned configuration reference

[Justin Mason <jm...@jmason.org>]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


Daniel Quinlan writes:
> jm@jmason.org (Justin Mason) writes:
> 
> > I'm not entirely sure how useful this is -- on one hand, it's
> > a great way to point to a single configuration setting.  OTOH,
> > it's another thing that can break, so I want to make sure >1
> > people think it's useful first ;)
> 
> Interesting.
> 
> Why not have different subdirectories for each version?  Easier and less
> apt to break.  Maybe have a version selector from a menu like CPAN.

That would be easier to do.  Probably a good idea, sth like:

    /ref/3.0.x/use_auto_whitelist.html

        displays 3.0.x doco

    /ref/2.6x/use_auto_whitelist.html

        displays 2.6x doco

    /ref/use_auto_whitelist.html

        displays "latest stable" doco, 3.0.x

and pages have the selector to display other versions, if they exist.

> Also, does this handle the configuration documentation changing slightly
> from version to version?  They all appear to be the same.

It just uses the latest, if the =item exists in >1 version.

- --j.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (GNU/Linux)
Comment: Exmh CVS

iD8DBQFBPiV0QTcbUG5Y7woRAtO8AJ4/1Dcsz5t9EqXRrfiLg8vCAW9KGgCgxApE
ulifaboTB2wp6IHUZF01S0c=
=7/zG
-----END PGP SIGNATURE-----

Re: new tool for website -- versioned configuration reference

[Daniel Quinlan <qu...@pathname.com>]

Justin Mason <jm...@jmason.org> writes:

> what, like what's already there?
>
>     http://spamassassin.apache.org/doc.html

Not at all.

| The POD documentation: (WARNING: for the latest development version!)
| [etc.]

That's all wrong.  There should NEVER EVER be a non-versioned
documentation link.  Listing either latest development or latest stable
is very very wrong.

  http://spamassassin.apache.org/doc/Mail_SpamAssassin_Plugin_Hashcash.html

That page should not exist unless the only thing on that page is a
dialog that looks like this:

  [SpamAssassin 2.64]
  [SpamAssassin 3.0.0]
  [SpamAssassin 3.0.1]
  [older releases]  

and nothing more.

The top documentation page should just have this:

  Select your version of SpamAssassin:

    [SpamAssassin 2.64]
    [SpamAssassin 3.0.0]
    [SpamAssassin 3.0.1]

  etc.

Daniel

-- 
Daniel Quinlan
http://www.pathname.com/~quinlan/

Re: new tool for website -- versioned configuration reference

[Daniel Quinlan <qu...@pathname.com>]

jm@jmason.org (Justin Mason) writes:

> That would be easier to do.  Probably a good idea, sth like:
> 
>     /ref/3.0.x/use_auto_whitelist.html

I'd strongly advocate providing versioned links for the current
documentation *first* and afterwards we can worry about option links.

  /ref/3.0.0/Mail::SpamAssassin::Conf.html

or whatever.
 
> It just uses the latest, if the =item exists in >1 version.

That's definitely not the right way and will definitely cause problems
and confusion.

Daniel

-- 
Daniel Quinlan
http://www.pathname.com/~quinlan/