Documenting unreleased features in the guide

[William Siegrist]

On May 17, 2008, at 8:45 PM, markd at macports.org wrote:
>>
> 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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 2421 bytes
Desc: not available
Url : http://lists.macosforge.org/pipermail/macports-dev/attachments/20080519/8cc63e5c/attachment-0001.p7s