Editing and updating the dCache Book
Obtaining source
Check out the book source from subversion. For details how to do this, see working with SVN.
Note that there is a branch in the dCacheBook for each release; here are some examples:
# check out dCacheBook for 1.9.5-series paul@zitpcx6184:~/SVN/dCacheBook$ svn co svn+ssh://svn.dcache.org/data/svn/dCacheBook/branches/1.9.5 Branch-1.9.5 # check out dCacheBook for 1.9.7-series paul@zitpcx6184:~/SVN/dCacheBook$ svn co svn+ssh://svn.dcache.org/data/svn/dCacheBook/branches/1.9.7 Branch-1.9.7 # check out dCacheBook for 1.9.8-series paul@zitpcx6184:~/SVN/dCacheBook$ svn co svn+ssh://svn.dcache.org/data/svn/dCacheBook/branches/1.9.8 Branch-1.9.8 # check out dCacheBook for 1.9.9-series paul@zitpcx6184:~/SVN/dCacheBook$ svn co svn+ssh://svn.dcache.org/data/svn/dCacheBook/branches/1.9.9 Branch-1.9.9 # check out dCacheBook for next major dCache release paul@zitpcx6184:~/SVN/dCacheBook$ svn co svn+ssh://svn.dcache.org/data/svn/dCacheBook/trunk Trunk
Gaining an overview
This is a XSLT stylesheet that displays the tree structure of a DocBook document (or portion thereof) as an ASCII-art tree. You can use it directly to get an overview of a particular chapter, part or the whole Book; for example, here's how to see the "Installing dCache" chapter:
xsltproc http://www.desy.de/~paul/DocBook/ascii-art.xsl install.xml
The --xinclude option is needed for parts and the whole book; for example, here's how to see the "Cookbook" part:
xsltproc --xinclude http://www.desy.de/~paul/DocBook/ascii-art.xsl cookbook.xml
and here's the whole book:
xsltproc --xinclude http://www.desy.de/~paul/DocBook/ascii-art.xsl Book.xml
Getting a suitable build environment
Read the file README in the root directory of the checked-out files; no, really, read it!
You should also install the hyphenation rules for fop; again, read the README file.
Building output
To generate output you need to type make and a target. For example, to build all output types, run the command:
paul@zitpcx6184:~/SVN/dCacheBook/Trunk$ make all
To see a list of all possible output types, run make by itself.
paul@zitpcx6184:~/SVN/dCacheBook/Trunk$ make The dCache Book --------------- Available main build targets: all -- build everything pdf -- build PDF versions [...etc...]
The most useful commands are make html to produce the HTML output, make pdf to produce the PDF output and make all to produce everything.
All the output will be local; nothing will be published on the dCache website.
Test-deploying output
If you want to update the book and want others to see what it will look like, you can test-deploy the book. This publishes all the output: PDF (A4- and Letter-size) and HTML (single- and multi-page) on the web page in a safe location. The pages are public but the location isn't published anywhere, so people outside dCache team will not know about it.
To make a test-deployed page, use the make test-deploy command.
paul@zitpcx6184:~/SVN/dCacheBook/Trunk$ make test-deploy [... lots of output ...] Book now updated at http://www.dcache.org/manuals/Book-1.9.9-test/
If successful, the last line will start "Book now updated at" with a corresponding URL. Different formats are available by appending something to the stated URL:
| (nothing) | multi-page HTML |
| Book.shtml | single-page HTML |
| Book-a4.pdf | A4-size PDF |
| Book-letter.pdf | Letter-size PDF |
Deploying output
When you need to update the live web-pages, use the make deploy command:
paul@zitpcx6184:~/SVN/dCacheBook/Trunk$ make test-deploy [... lots of output ...] Book now updated at http://www.dcache.org/manuals/Book-1.9.9-test/
Putting patches on Review-Board
When creating a new review request you are asked for absolute patch of the repository where the patch was created. If you did that inside the branches root directory (e.g., inside "/space/dCacheBook/trunk/") put "/" here.
