NAME

getsakaihelp - download Sakai help docs from the IU KB in XML form and transform them to HTML


SYNOPSIS

    getsakaihelp --user <uname> --password <pword> [options] [docid...]


    audience     REST parameter for rendering document titles 
                 (default: "sakaihelp")
    cc           email address to receive a CC of comments 
    css          path to css file for help documents 
                 (default "/portal/help/TOCDisplay/content.hlp?docId=")
    docdir       the directory to write the HTML files to
                 (default "docs")
    domain       REST parameter for fetching Sakai documents
                 (default "sakai21")
    domainclass  REST parameter for fetching Sakai documents
                 (default "sakai21")
    force|f      download all docs even if they are up-to-date
    link         Base URL for inter-document links
                 (default "/portal/help/TOCDisplay/content.hlp?docId=")
    button       Flag for adding a link to "https:oncoursehelp.iu.edu/comments.cgi"
                 (default ON)
    docinfo      Flag for adding doc metadata at end of text
                 (default ON)
    refs         Flag for adding cross-reference links at end of text
                 (default OFF)
    password     Your REST password
    server       URL of the KB's REST server
                 (default "remote.kb.iu.edu/REST/v0.2"
    user         Your REST username
    help|h       brief help message
    Help|H       full help


DESCRIPTION

getsakaihelp is a simple REST web services client that retrieves and transforms Sakai help documents. It will download documents, check for errors, and transform them into HTML suitable for displaying in the Sakai Help Tool.

The only ``nonoptional'' options are --user|u and --password|p which you must set to the credentials you received from the Knowledge Base development team by sending a request to kb-clients@kb-dev.indiana.edu. So to simply download all current Sakai help documents, enter:

    getsakaihelp -u <uname> -p <pword>

If no document ids are provided on the command line, getsakaihelp will download an XML document from the KB containing a list of all Sakai help documents, with timestamps. It will check for a saved version of this list (see old_docid_list.xml below), compare timestamps with the newly received list, and only download documents that are out-of-date. To override this and force getsakaihelp to download all the files, specify --force|f on the command line. Or if you want to download only certain documents, put those four-letter docids as arguments on the command line.


OPTIONS

--audience
A REST parameter to tell the KB server how to render the titles of documents. This should always be 'sakaihelp'.

--button
Flag for whether to create a button at the end of every document that links to a <a href=``https://oncoursehelp.iu.edu/comments.cgi''>comment form</a> for users to send feedback to the KB (and the email address entered for --cc.) Because the KB highly values user feedback, this option is turned on by default. To turn it off, specify <code>--nobutton</code> or <code>--button 0</code> on the command line.

--cc
An extra email address to which to submit comments about the document (see --button). The form linked to by the button will email kb@iu.edu and send a copy to the email address you enter here. (When entering an email address, you must escape @ with a backslash. E.g., root\@localhost).

--css
The url of a css file that should be used to render the HTML help document.

--docdir
The directory to which to write the rendered HTML files.

--docinfo
Flag for whether to show document metadata at the end of the text. The metadata consists of the document id, and the last time it was updated.

--domain, --domainclass
REST parameters to tell the KB server exactly which version of the Sakai documentation you want. Each version of Sakai will have a different domainclass and domain; e.g., Sakai 2.2 will have --domainclass='sakai22' and --domain='sakai22', but the audience will still be 'sakaihelp'.

--force|f
Download all available documents even if they are up-to-date.

--link
The base URL for inter-doc links. For links to other help documents to work in a Sakai Help Tool environment, it must include the path to the help tool itself, in order for the help tool to bring up the linked document. If you are displaying the help documents standalone this parameter should be null to indicate that the HTML files are all available in the same directory.

--password|p
The REST password you obtained from the IU KB by writing to kb-clients/@kb-dev.indiana.edu.

--refs
A flag for whether to show a section of cross reference links at the bottom of the document. This is a feature of KB documents that isn't being used in the Sakai Help Tool, though it could be used if you are using the help documents standalone.

--server
The URL for the KB REST server.

--user|u
The REST username you got from the IU KB by writing to kb-clients/@kb-dev.indiana.edu. You need it to connect to the KB REST server. getsakaihelp also passes this value to the XSLT engine in order to include it with the HTTP parameters sent to the comment form, to help the KB track where the comment came from.

-help
Prints usage, options, and arguments and exits.

-Help
Prints the manual page and exits.


ARGUMENTS

docid
You can enter one or more four-letter docids on the command line to restrict getsakaihelp to only downloading those documents. Specifying docids will force them to be downloaded, even if they are up-to-date.


FILES

old_docid_list.xml
An XML file containing a list of all available docids and their timestamps. getsakaihelp will try to save a new version of this file every time it connects to the KB server. If the file doesn't exist, getsakaihelp will download all available documents.

XSLT/preprocess.xsl
An XSLT template that applies a unique id to every element of the document, to allow for applying CSS rules to images in a way particular to the Knowledge Base. getsakaihelp transforms the XML document with this template before transforming it to HTML.

XSLT/doc.xsl
The XSLT template that transforms the documents from XML to HTML. It has extensive internal documentation.