Hi Documentation Community, I want to let people know about some of the changes that will take place for the evergreen documentation in master and as of version 2.2 and beyond.
1) asciidoc: The official format for contributions will be asciidoc. This entails several advantages: - asciidoc is easier to write. No more complicated DocBook XML tag to memorize. - asciidoc files can be read more easily as stand alone document compare to raw docbook xml files. - files in the code can be more easily migrated/imported into the documentation (such as the README file for installation) - some important contributors are already using asciidoc for their documentation (ESI, Dan Scott) For authoring in the asciidoc format you can : Review the official asciidoc usergude: http://www.methods.co.nz/asciidoc/userguide.html Check out this asciidoc cheat-sheet: http://powerman.name/doc/asciidoc Or look at some of the files we have added to the repository: https://github.com/rsoulliere/Evergreen-DocBook (.txt files are asciidoc files) These files should give you some idea about the structure of files to be included. 2) I have begun to reorganize the documentation. See: http://open-ils.org/dokuwiki/doku.php?id=evergreen-docs_2.2:outline. Note: This is a work in progress. Please flesh out the chapters/sections under each part. Feel free to reorganize as needed. In other words, hack away! 3) I have adjusted the repo directory structure accordingly in the master of the repository: See: https://github.com/rsoulliere/Evergreen-DocBook Changes include: Directories corresponding to the the specific areas of library operation (eliminating the generic "stafftasks" directory): circulation cataloging opac (using the opac) serials reports Directories for this other more general areas: installation admin (for files related to system configuration/customization, server admin and local admin) development (developer stuff) a "media" directory for images, etc used in any of the chapters of the documentation... Note that the final documentation product has not changed much at this time: If you check out the documentation page at: http://docs.evergreen-ils.org/ you will see that there is a link to 2.2 documentation in both hHTML and PDF formats which is under development. This is produced from the asciidoc files in the master repo. The toolchain to produce the documentation is asciidoc -> DocBook XML -> (HTML and PDF). The reason the DocBook XML creation step (automated process) is to produce the PDF files. Authors will only need to create and edit plain asciidoc files for 2.2 documentation (not XML). However, DocBook XML is still the format for authoring in 2.1 and other prior versions of the documentation. Thanks, Robert Robert Soulliere, BA (Hons), MLIS Systems Librarian Mohawk College Library [email protected] Telephone: 905 575 1212 x3936 Fax: 905 575 2011 This E-mail contains privileged and confidential information intended only for the individual or entity named in the message. If the reader of this message is not the intended recipient, or the agent responsible to deliver it to the intended recipient, you are hereby notified that any review, dissemination, distribution or copying of this communication is prohibited. If this communication was received in error, please notify the sender by reply E-mail immediately, and delete and destroy the original message. _______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
