Filtered by category Documentation, 11 - 18 of 18 Postings (
all,
summary)
Created by Robert Taylor, last modified by Benjamin Brink 29 Jun 2017, at 10:36 AM
The OpenACS Documentation is organized as follows:
- Core Documentation ( 1:1 direct copy of what exists )
- Package Documentation ( 1:1 direct copy of what exists )
- Subsystems Documentation ( systems multiple-perspectives view )
Created by Rocael Hernández Rizzardini, last modified by Benjamin Brink 29 Jun 2017, at 10:33 AM
This is Approach 3 of the en:Documentation_Project as defined in en:Documentation_Project_Discussion.
Official documentation will go into openacs.org/test-doc (to be renamed) generate from there the html pages for documentation, therefore the first result is to update the documentation to reflect current tools, version, correct commands, all done within that wiki instance
The process for generating technical documentation is:
- Update that documentation wiki instance named doc-head
- Once the documentation is ready, freeze it doing a export/import process from /doc/head to a new instance (i.e. /doc/5-5-0)
- No write permissions for the public will be granted to this frozen instances
- Use an alternate template to distinguish between /doc/head and the frozen ones
- Generate the static html documentation based on the wiki-frozen instance (/doc/5-5-0)
- Using as template_file the view-oacs-docs
- Available here: http://alice.wu-wien.ac.at:8000/xowiki/listing?m=list
- Have to be placed on www dir of xowiki package
- Also the parameter top_includelet have to be in blank for the wiki-frozen instance
- Example on how the doc will be available in the wiki-frozen instance: http://alice.wu-wien.ac.at:8000/test-doc/for-everyone
- Options for the static content:
- One large HTML file and/or (book-print prototype)
- One HTML file per chapter and/or (tutorial-advance prototype)
- Same granularity as in /doc/head
- Get the documentation using wget
- The html files will not have an extension, this may cause them to not be interpreted as html and returned as plain text on some web servers, to be safe, rename the files to have an extension. Run the following script on the directory containing the static html files.
- Commit into the CVS, branch and tag appropriately following the branch/tag conventions for the specific release.
- Add a link of this new /doc/5-5-0 into online documentation index openacs.org/doc and a map it in the site map to /doc/current
Then the process can start again for the next documentation release.
To-Do
Still missing a way to transform to independent html files with index / navigation within it (right now only produces a one big html). (done by Gustaf)- New /doc has to have a link to the various online (xowiki) frozen versions of the documentation.
- Document the document formatting/markup rules in the wiki instance and the static documentation.
- Probably there is already formats for technical documentation available, produced, or at least some guidelines.
- Openacs.org/doc will be replaced with the wiki-documentation (/test-doc instance renamed to /doc/head)
- Provide an index to link to all frozen documentation releases.
- Current /doc can be renamed to /doc-5-1
- Assign someone to udpate the documentation, follow the process and release documentation.
Following moved to this context, which is using approach discussed by Malte below:
Malte here:
Instead of doing it manually (though this does have some merit), I would go and modify the script Gustaf provided to import the whole documentation in one go into a new XoWIKI instance with the structure (page_order) that has been added in XoWIKI 0.42 taken from the chapters of the documentation so that we do have an exact mirror of the documentation as it stands now.
Once this is achieved we could go on and assign categories to the documentation, allowing for an alternative view on the documents (so you could say "instead of showing the whole documentation only show the documents for a specific category"). Probably this needs some more detailed discussion with Gustaf finding out how this could be achieved in XoWIKI and what would make most sense. Ideally we could provide a different structure based on the target group (e.g. category) but this is probably shooting too far. Getting categorization and page ordering in a decent shape should provide us a lot of possibilities.
- One can use the follwing script to generate the page objects and load it via xowiki/admin/import into an xowiki instance; this can be improved in many places, but gives you the idea
- # by Gustaf Neumann
- # load doc pages into xowiki -gustaf neumann
# for tdom
lappend auto_path /usr/local/aolserver4/lib
package require tdom
package require XOTcl; namespace import ::xotcl::*
package require xotcl::serializer
set docpath /usr/local/openacs-4/packages/acs-core-docs/www/
namespace eval ::xowiki {
Class create Page -parameter { {lang en} {description ""} {text ""}
{nls_language en_US} {mime_type text/html} name title text }
set c 0
foreach docpage [glob $docpath/*.html] {
set f [open $docpage r]; set data [read $f]; close $f
dom parse -html $data doc
$doc documentElement root
set content ""
foreach n [$root selectNodes //body/*] { append content [$n asHTML] \n }
set p [Page create page[incr c] -name en:[file tail $docpage] \
-title [[$root selectNodes //title] asText] \
-text [list $content text/html]]
puts [::Serializer deepSerialize $p]
}
}
Suggestion by Rob Taylor:
1a. Move all but maybe the first and last 2 items from https://openacs.org/doc/dev-guide.html to https://openacs.org/doc/kernel/dev-guide.html and refer to them in context of the kernel package (or whatever package their code is in). That helps developers see appropriate context. (This will likely require a board discussion and TIP
Created by OpenACS community, last modified by Benjamin Brink 24 Jun 2017, at 05:19 AM
The history of OpenACS documentation: ..began by building on a good documentation base from ArsDigita's ACS in the late 1990's. The ACS documentation was largely written in docbook. Some sections of the documentation, however, lacked details and examples; others simply did not exist. The OpenACS community began meeting the challenge by identifying needs and writing documentation on an as needed basis.
By having documentation dependent on volunteers and code developers, documentation updates lagged behind the evolving system software. As significant development changes were made to the system, existing documentation became dated, and its value significantly reduced. The valiant efforts that were made to keep the documentation current proved too difficult as changes to the system sometimes had far-reaching affects to pages throughout the documentation. System integration and optimization quickly rendered documentation obsolete for developers. The code became the substitute and source for documentation.
There are many thousands of lines of code, and few developers tracking changes and publishing the changes. Subsequently features and advances to the OpenACS system went unnoticed or were not well understood except by the code authors. Work was duplicated as a consequence of developers not realizing the significant work completed by others. New developers had to learn the system through experience with working with it and discussion in the forums. Informal sharing of experiential and tacit knowledge has become the OpenACS community's main method of sharing knowledge.
Around 2006, efforts were made to build a consensus in new ways to overcome existing documentation limitations. Like most any diverse community, a consensus could not be reached. Time has distilled efforts into three approaches that augment OpenACS' primary source of documentation: OpenACS code itself.
Created by OpenACS community, last modified by Gustaf Neumann 20 Apr 2017, at 06:44 PM
OpenACS for developers
Features
Besides the quality components of Openacs (See: en:openacs-system), OpenACS has these enterprise-quality features for developers:
- high-performance XML data processing with easy, powerful Tcl scripting functionality using en:tdom (as of OpenACS version 5.0)
- XOTcl object-oriented scripting, which combines the ideas of scripting and object-orientation in a way that preserves the benefits of both (as of OpenACS version 5.3)
- Automated testing (see: en:Testing_with_Selenium and en:testing-with-tclwebtest)
- Flexible and easy caching, for improving the performance of your websites. https://openacs.org/doc/tutorial-caching.html
- programming in Tcl with AOLserver - A lightweight, simple, extremely fast scripting language that features a clean, easy-to-understand API (Application Programming Interface) for generating websites from the database. (See: https://openacs.org/doc/programming-with-aolserver.html )
- pooled DB connections (which reduces database connection startup and tear down time), much like the technique JDBC uses, but predating it by many years. (See: http://www.aolserver.com/docs/admin/dbadmin.html#2 )
- Component package system for easy installation and upgrading of packages (See: https://openacs.org/doc/apm-design.html
- Upgrade paths for code and database schemata (See: https://openacs.org/doc/tutorial-upgrade-scripts.html )
- Full internationalization, including an excellent workflow for translating content into new languages. (See: https://openacs.org/doc/i18n.html )
- Fully functional content repository and content management system. (See: https://openacs.org/doc/cms/cms-intro.html )
- An elegant templating system that separates code from presentation of content. (See: https://openacs.org/doc/templates.html )
- An object system that resides on top of the database, permitting site developers to create complex applications using an object API. Examples include an object level permissions system, audit trails, and ability to relate one object to another. (See: https://openacs.org/doc/object-system-requirements.html )
- OpenACS is released as open source under the GPL license, with millions of lines of open-sourced applications available to use as examples. There are also pre-written packages for you to use or adapt.
will be pulling in docs from here: https://openacs.org/doc/acs-package-dev.html and https://openacs.org/doc/acs-plat-dev.html
Integrated Development Environments (IDE)
These text editors are commonly used when coding on OpenACS:
Bibliography and Credits
See en:doc-credits.
Created by OpenACS community, last modified by Gustaf Neumann 01 May 2015, at 09:43 AM
To try OpenACS, you might lease a hosted system with OpenACS installed on it:
Created by OpenACS community, last modified by Torben Brosten 18 Mar 2007, at 09:38 AM
Documentation Credits
Bibliography: Where did this document come from?
This document is really just plagiarism from a number of documents that came before it. If something is used without proper credit, let us know so we can fix it right away.
The short bibliography:
- OpenACS Documentation Versions 4.6.2 to present were edited by Joel Aufrecht.
- ArsDigita installation guide
- OpenACS 3.x installation guide
- Gilbert Wong's FreeBSD installation guide
- Vinod Kurup's Brief OpenACS4 installation guide
- Joel Aufrecht's OpenACS 4.5 Quick Guide
Known authors and contributors
Acknowledgments for versions of the above documents go (in no particular order) to Bryan Quinn, Adam Farkas, Brian Stein, Doug Hoffman, Ravi Jasuja, Hiro Iwashima, Ryan Lee, Jonathan Goler, Audrey Mcloghlin, Doug Harris, Zvi Boshernitzan, Michael Yoon, Cesar Brea, Dennis Gregorovic, David Fullagar, Chris Spears, Kevin Tupper, Michael Duffy, Simon Carstensen, Dave Bauer, Tracy Adams, Greg Haverkamp, Philip Greenspun, Jin Choi, Sean Yamamoto, David Cohen, Chris Rasch, Richard Li, Jon Griffin, Roberto Mello, Gilbert Wong, Don Baccus, Ben Adida, Michael Cleverly, Janne Blonqvist, Jonathan Ellis, Janine Sisk, Jade Rubick, Chris Hardy, Jonathan Marsden, Vinod Kurup, Charles Hall, Tom Jackson and Karl Lehenbauer.
Others who have contributed to this document: Robert Taylor, Ryan Gallimore, Gustaf Neumann, Torben Brosten, Don Baccus, Roberto Mello, Talli Somekh, Dave Bauer, Jim Lynch, Jon Griffin, Daryl Biberdorf, Bjorn Thor Jonsson, Jade Rubick, Fred Yankowski, Dan Chak, Sebastiano Pilla, Reuven Lerner, Malte Sussdorff, Stan Kaufman, Pascal Scheffers and Rocael Hernández.
Contributers to xowiki documents, including this one: en:contributors
Finally, much appreciation and thanks goes to the OpenACS community, who have provided much valuable feedback in the fora, which compromises the goals of this documentation.
Created by Carl Robert Blesius, last modified by Torben Brosten 12 Jan 2007, at 01:51 PM
This page has been deprecated. See en:Documentation_Project
After years of trying to keep the Docbook based OpenACS documentation up-to-date there has been a movement towards putting the information into a more easily editable format (so you can easily add to this documentation).
This document is part of that migration effort and as such is a work in progress (use the edit button to help).
This WikiDoc Replaces:
