[OracleOSS] [TitleIndex] [WordIndex]

Sourcebo/ContentDocumentation

Sourcebo Downloads

Projects need documentation. At least, those that want users do. Whether extensive manuals or a simple readme, a CMS should offer a way to make documentation available.

Sourcebo does this via the documentation/ subdirectory of the content repository and description files. Documentation files are managed almost identically to Downloads.

Adding Documentation to a Project

Adding documentation to a project is just like adding downloadable files. Copy the documentation files to the documentation/ subdirectory of the content repository and check them into Subversion. They are now a part of the content repository.

$ cp myproject-reference.pdf $HOME/projects/myproject-content/documentation/
$ cd $HOME/projects/myproject-content/documentation/
$ svn add myproject-reference.pdf
$ svn commit -m 'Added reference documentation' myproject-reference.pdf

Just like downloads, subdirectories are allowed.

Making Downloads Visible

Like downloads, documents are not visible in the "Docs" section until they have a description file.

To make a document visible, create a description file by taking the file name and adding a .desc extension. So, the file myproject-reference.pdf has a description file of myproject-reference.pdf.desc. When Sourcebo looks at the documentation/ directory, it checks every <filename> for a corresponding <filename>.desc. Each valid file and description creates an entry on the "Docs" page.

The description file for a download has only one stanza:

description:
    title = File Title
    description = Source archive

The descriptiion attribute is mandatory. The title attribute is optional. If there is no title specified, the filename is used as a title. So, for your source archive documentation/myproject-reference.pdf, you may use a description file of documentation/myprject-reference.pdf.desc:

description:
    title = MyProject Reference Guide
    descriptiion = A reference for all possible uses of MyProject

Subdirectories Too

If you want a subdirectory of documentation/ to appear on the "Docs" page, make a description file for the subdirectory. For example, documentation/benchmarks may have have a description documentation/benchmarks.desc:

description:
    title = Benchmarks
    description = Various benchmarks of MyProject.

The "Docs" Page

For every visible document, the "Docs" page displays the title, description, md5sum, and modification date. The title is clickable to open the actual document. The md5sum is calculated by Sourcebo, and can be used by the downloader to verify file contents.


2012-11-08 13:01