Forum OpenACS Q&A: URLs of most current documentation: moving targets

Can we make the version of the documentation installed on openacs.org ( https://openacs.org/doc/package-name-or-doc-file-name) the most current version of the documentation (https://openacs.org/doc/openacs-4-6-3/ ) so that we have permanent urls to the most recent version of the docs?

Right now the urls to the most recent docs seem to be changing fast:
https://openacs.org/doc/openacs-4-6-3/
https://openacs.org/doc/openacs-4-6-2/
https://openacs.org/doc/openacs-4/
https://openacs.org/doc/openacs-3/

Collapse
Posted by Jade Rubick on
This is a good idea!
Collapse
Posted by Joel Aufrecht on
so https://openacs.org/doc/openacs would always return the most recent doc?  Is there a consistent scheme we could use for other docs?  /doc/installed?  /doc/dotlrn?
No, https://openacs.org/doc/ should always be the newest version of the doucmentation. If there is a good reason to create an archived version (e.g. 3 -> 4 or prejoelian docs -> joelian docs) then we create one here: https://openacs.org/openacs-n and add a link to the doc index that is distributed with all versions of OpenACS. This can happen on its own if we commit to keeping the openacs.org cvs in sync with the stable branch of openacs. We then add to the package documentation as usual (e.g. /doc/dotlrn/ ) and benefit from having static urls (e.g. general comments) Here is a suggestion of how the left column in the doc index page could change to reflect this (and replace the page that comes up now):
Getting Started
        - OpenACS 4.6.3 Release Notes
	- Required Software
	- Unix Installation Guide
        - Windows Installation Guide
	- Mac OS X Installation Guide
	- Upgrading
	- Developer Tutorial
        - API Browser for this OpenACS instance

Full Table of Contents

Primers and References
        - OpenACS FAQs
        - OpenACS CVS Browser
        - AOLserver Documentation 
	  (the Tcl Developer's Guide in particular.)
        - Tcl for Web Nerds
        - SQL for Web Nerds

Archive
        - OpenACS 4.6.2 Documentation
        - OpenACS 4.6 Documentation
        - OpenACS 3.2.5 Documentation

Documentation Improvement Project
        - Help improve OpenACS documentation

Collapse
Posted by Joel Aufrecht on
That sounds like a good idea to me.  I'll adjust the /packages/acs-core-docs/www/index.adp page to reflect the extra links, which is a good idea anyway.  Implementation should mean creating a symlink - it would be nice if openacs.org ran on straight code, but that's going to take a while and shouldn't hold up these sorts of improvements.  So I think we can just roll this out with the next dot-release or, I guess, any time after the new index page is ready.  The only drawback is we lose edit-this-page ability on openacs.org/doc.

Think of losing etp ability as a reduction of what we have to worry about. Consequently I am going to start pushing the different pieces of .LRN documentation floating around in etp (and elsewhere) into the /doc/dotlrn/ folder (under cvs control) and pushing descriptions of functionalities that are not specific to .LRN into the individual package docs (news, faq, forums, etc.).

Below is the html for the index page again (I closed an open html tag in the original and added the education link). Now the only thing missing from the old page is "Miscellaneous Documentation" (which only contains an openacs migration doc) and "Using CVS". Where do those two docs belong?

Getting Started
        - OpenACS 4.6.3 Release Notes
	- Required Software
	- Unix Installation Guide
        - Windows Installation Guide
	- Mac OS X Installation Guide
	- Upgrading
	- Developer Tutorial
        - API Browser for this OpenACS instance

Full Table of Contents Primers and References
        - OpenACS FAQs
        - Learning OpenACS
        - OpenACS CVS Browser
        - AOLserver Documentation 
	  (the Tcl Developer's Guide in particular.)
        - Tcl for Web Nerds
        - SQL for Web NerdsArchive
        - OpenACS 4.6.2 Documentation
        - OpenACS 4.6 Documentation
        - OpenACS 3.2.5 DocumentationDocumentation Improvement Project
        - Help improve OpenACS documentation

Collapse
Posted by Joel Aufrecht on
The CVS instructions should move into a the developer chapter of the docs.  The postgres migration instructions will move into the maintenance/upgrade section, and hopefully one day someone will contribute 7.1->7.3 instructions as well.  I've added this change (all the changes to index.adp and moving these docs into acs-core-docs) to my work list.
Collapse
Posted by Joel Aufrecht on
index.adp is updated and ready.  That is, when openacs.org/doc points directly to packages/acs-core-docs/www/index.adp (from HEAD, post-4.6.3), index.adp will include links to old versions and the other things currently on the ETP at that address.