Documenting unreleased features in the guide

[markd at macports.org]

>> I think two branches of the released guide is cumbersome.  And  
>> though I
>> don't like including version numbers in the guide per se, but I'll  
>> throw
>> out another alternative that is sort of a "third way" betwen 1 and  
>> 2.  Use
>> DocBook "profiling"; some vendors refer to this feature as  
>> "conditional
>> text".  So the xml in the guide that represents features in HEAD are
>> flagged as such, and two guides are cranked out by the stylesheets.   
>> So we
>> would in fact have two versions of the guide as far as generated  
>> html, one
>> for the released version and one for HEAD, though only one source  
>> tree.
>> But as I said, I think we'd need to get a handle on listing base  
>> changes
>> that need documenting before this would really work.
>
>
>
>This idea seems like a decent compromise. If we do this, I would like  
>to see a link at the top of each page to switch to the other versions.  
>So maybe guide.macports.org is the current Trunk/HEAD docs, and  
>guide.macports.org/1.6.0/ is the docs for v1.6.0. At the top of  
>guide.macports.org is a link to /1.6.0/  and the top of /1.6.0/ has a  
>link to the Trunk/HEAD docs.
>
>An example of this is the documentation for Django:
>
>http://www.djangoproject.com/documentation/
>
>Now, under this model, its up for debate as to which version lives on  
>the "top" of guide.macports.org. I can see reasons for both, so I dont  
>have a strong preference either way.
>
>-Bill

The django site method looks like a good way to present multiple versions.
 But even though I don't think it would be hard to do, I still have some
problems with doing it.  The problem I see is that:

1) We don't sufficiently distinguish between versions of the program
itself to adequately distinguish versions of  documentation, since doing
that assumes a clear distinction already.

2) MacPorts versions tend to be extremely similar to each other it seems
to me, and it seems to me keeping multiple versions of a document implies
some extensive changes.  So on the one hand I wonder if it is worth it; on
the other I wonder if it will be confusing to present several versions of
a document so similar. 

As far as point 1), some have suggested we shouldn't use MP releases at
all and call everything a beta for similar reasons I think.  I don't want
to advance an opinion one way or the other on that, but I think the
question simply rises again in the docs.  Though "conditional text" isn't
hard I don't think, I worry about confusion about which features will be
released with the next version of base generating confusion on the doc
team about to write the docs.

Though I know I said I don't like using version numbers in the guide
generally, for this one instance maybe it isn't a bad idea to just add a
version number and remove it after the next code release.  Right now, the
fetch feature I documented from HEAD recently is the only instance I'm
aware of where HEAD features are in the guide.  Perhaps we could just wait
and see if versioning problems come up again frequently before using more
advanced methods.

Mark