wiki:dCacheBook
Last modified 6 years ago Last modified on 04/19/12 16:46:45

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.shtmlsingle-page HTML
Book-a4.pdfA4-size PDF
Book-letter.pdfLetter-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.