From 93879418c653a7b9319c45dc23d470c1f02be08b Mon Sep 17 00:00:00 2001 From: William Victor Mote Date: Mon, 21 Apr 2003 19:48:40 +0000 Subject: [PATCH] Move documentation README to a web page. git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@196288 13f79535-47bb-0310-9956-ffa450edef68 --- src/documentation/README | 107 --------------- src/documentation/content/xdocs/dev/book.xml | 1 + src/documentation/content/xdocs/dev/doc.xml | 130 +++++++++++++++++++ 3 files changed, 131 insertions(+), 107 deletions(-) delete mode 100644 src/documentation/README create mode 100644 src/documentation/content/xdocs/dev/doc.xml diff --git a/src/documentation/README b/src/documentation/README deleted file mode 100644 index 9f5f82d26..000000000 --- a/src/documentation/README +++ /dev/null @@ -1,107 +0,0 @@ - - HOW TO UPDATE THE FOP WEBSITE - -Background --------------- - 1. The FOP web site & documentation are generated using forrest - (http://xml.apache.org/forrest/). - 2. There are two general ways to update the FOP web repository, each described - in more detail below: - a. the forrestbot on the Apache server - b. a local copy of Forrest - 3. Files related to the web site reside in the following places: - a. FOP source repository (cvs): - icarus.apache.org/home/cvs/xml-fop - b. interim web site (html, pdf, etc.) - 1) if forrestbot is used: - Location is unknown & unimportant to us. - Content can be viewed, refreshed, and published at: - http://forrestbot.cocoondev.org - 2) if local Forrest is used: - Files will be generated on your local machine. - c. FOP web repository (cvs): - icarus.apache.org/home/cvs/xml-site/targets/fop - d. FOP live web site: - somewhere on daedalus.apache.org - 3. The flow of data from our project committers to the actual web site is as - follows: - a. Source code changes are committed to the cvs repository by developers. - b. An interim web site is built using one of two methods: manual/local or - forrestbot. - c. The interim web site is committed to the FOP web repository, again using - one of two methods: manual/local or forrestbot. - d. Every six hours (midnight, 6am, noon, 6pm Pacific time), a script copies - the contents of the web site repository to the server for the FOP live - web site. For support on this process: - 1) The CVS update logs can be viewed at - http://www.apache.org/~rubys/updatesite.logx, where "x" is a number - from 1-4, these four files being the updates done over the past 24 - hours. Review the most recent log file for clues. - 2) the script is maintained by Sam Ruby (rubys@apache.org). Contact him - for further help. - -Forrestbot or Local Forrest? ----------------------------- -By far, the easiest way to generate an interim web site and to update the FOP -web repository is to use the forrestbot on the Apache servers. - -Advantages: -1. Easy to use. -2. Always using the "approved" versions of Forrest and supporting - infrastructure. -3. No manual steps with attendant human error. - -Disadvantages: -1. Ties up server resources. -2. Requires a server login (see http://forrestbot.cocoondev.org for instructions - about how to obtain one). - -For minor or pure documentation changes, use the forrestbot. For major changes, -such as sitemap building, that will require many edit/build/test/debug cycles, -use a local Forrest instead. Also, even for major changes, it is probably better -to do the final build and commit using the forrestbot, after all of the -debugging has been completed on your local machine. - -Updating the Web Site Repository using the Forrestbot ------------------------------------------------------ -To use the forrestbot, simply follow these steps: -1. Make sure your changes are committed to the FOP source repository. -2. Open http://forrestbot.cocoondev.org in your browser. -3. Login. -4. In the "Select a module" box, select "xml-fop". -5. Click the "refresh" button to have the interim site built. On-screen - instructions tell you how to view the log as the build progresses. -6. After the build has completed, click "xml-fop" in the list of preview sites. - The interim site will be displayed in a frame. -7. After you are satisfied with the interim site, commit it to the FOP web - repository by first making sure that "xml-fop" is still selected in the - "Select a module" box, then clicking "publish". Again, you can watch the - log as it is built. -8. Wait for the next 6-hour update cycle and check the live web site. - -Updating the Web Site Repository using a Manual/Local Forrest -------------------------------------------------------------- - 1. Note: Forrest needs to be run on a machine with a graphical environment (it - will fail in a headless environment when it tries to use FOP to generate - the PDF files). - 2. checkout the xml-forrest module (same repository as xml-fop). - 3. checkout the xml-site/targets/fop module (same repository as xml-fop). - 4. you will also need access to a current xml-fop sandbox (you probably already - have one) - 5. cd to xml-forrest - 6. run: build.sh(bat) dist to build forrest - 7. set environment variable FORREST_HOME=~/xml-forrest/build/dist/shbat - where ~ is the directory in which xml-forrest is installed - (see http://xml.apache.org/forrest/your-project.html for details) - 8. set environment variable PATH=$PATH:$FORREST_HOME/bin - 9. cd to xml-fop directory -10. run forrest(.bat), which will build the web-site documents in - xml-fop/build/site. -11. To update the actual website, copy the generated documents - (in xml-fop/build/site) to xml-site/targets/fop on your local machine. - (This could also be done by sym-linking this destination before the build.) -12. Consider whether your final build and publish should be done using the - forrestbot on the Apache servers (see discussion above). Otherwise, commit - xml-site/targets/fop. - -Last Line of $RCSfile$ \ No newline at end of file diff --git a/src/documentation/content/xdocs/dev/book.xml b/src/documentation/content/xdocs/dev/book.xml index 66907106d..ebe7d515b 100644 --- a/src/documentation/content/xdocs/dev/book.xml +++ b/src/documentation/content/xdocs/dev/book.xml @@ -30,6 +30,7 @@ + diff --git a/src/documentation/content/xdocs/dev/doc.xml b/src/documentation/content/xdocs/dev/doc.xml new file mode 100644 index 000000000..8f7cfddac --- /dev/null +++ b/src/documentation/content/xdocs/dev/doc.xml @@ -0,0 +1,130 @@ + + + +
+ Managing FOP Documentation +
+ +
+ General Information +

All raw documentation content is managed in the FOP CVS repository. +Updates should be committed to the repository, then the repository files are used to generate usable output. +The remaining discussions on this page assume that the CVS repository is the starting place for processing. +The path to the documentation is xml-fop/src/documentation/content/xdocs.

+ All documentation is maintained on the trunk. +Although we are currently maintaining two sets of code (trunk and maintenance), there is only one set of documentation. +Most of the user and developer doc is common to the two environments, and differences are highlighted where necessary. +The major exception to this rule is the design doc, which currently exclusively pertains to the trunk (redesign). +Maintenance branch releases either copy the trunk content to the maintenance branch or use the trunk content directly for doc builds. +

Basic documents are stored in XML files, and use DTDs provided by Apache Forrest.

+
+
+ Website +
+ Background +

The FOP web site and documentation are generated using Apache Forrest.

+

The following table summarizes the flow of data to the FOP website in chronological order:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ProcessesFilesStateViews
.FOP source repository (cvs) at icarus.apache.org/home/cvs/xml-fopRaw XML and other contentViewCVS
+ Forrestbot "refresh". Automatically done every six hours. Can be manually refreshed by authorized users at the Forrestbot Web Interface. + Physical location unknown and unimportant to usweb-readyContent can be viewed here.
Forrestbot "publish". Always done manually at the Forrestbot Web Interface.FOP web repository (cvs) at icarus.apache.org/home/cvs/xml-site/targets/fopweb-ready +
Automatic Live Site Update every six hours (midnight, 6am, noon, 6pm Pacific time).FOP live web site, somewhere on daedalus.apache.orgweb-ready +
+
+
+ Forrestbot "refresh" Step-by-Step + The Forrestbot "refresh" is automatically run on the server every six hours. Only follow the steps below if you need to check the results more promptly than that allows, or if you need to "refresh" in preparation for a "publish". +

To manually use the Forrestbot "refresh", simply follow these steps:

+
    +
  • Make sure your changes are committed to the FOP source repository.
    • +
  • Open http://forrestbot.cocoondev.org in your browser.
    • +
  • Login.
    • +
  • In the "Select a module" box, select "xml-fop".
    • +
  • Click the "refresh" button to have the interim site built. +On-screen instructions tell you how to view the log as the build progresses.
    • +
+
+
+ Forrestbot "publish" Step-by-Step +

To "publish" the Forrestbot output to the FOP Web repository:

+
    +
  • Make sure you are satisfied with the "refreshed" site.
    • +
  • Open http://forrestbot.cocoondev.org in your browser.
    • +
  • Login.
    • +
  • In the "Select a module" box, select "xml-fop".
    • +
  • Click the "publish" button. +On-screen instructions tell you how to view the log as the build progresses.
    • +
  • Wait for the next 6-hour live-site update cycle and check your changes.
    • +
+
+
+ Live Site Update +

If there are problems with the live site update (the process of copying the web site contents from the FOP web repository to the live site:

+
    +
  • The CVS update logs can be viewed at http://www.apache.org/~rubys/updatesite.logx, where "x" is a number from 1-4, these four files being the updates done over the past 24 hours. +Review the most recent log file for clues.
    • +
  • The script is maintained by Sam Ruby (rubys@apache.org). +Contact him for further help.
    • +
+
+
+ Using a Local Forrest + Most documentation content changes do not require a local copy of Forrest. +In general, use the Forrestbot instead. Forrestbot is easy to use, always uses the "approved" methodology, and has fewer error-prone manual steps. +

There are some situations where you may want to have a local Forrest installation. For example, you do not want to tie up server resources testing major changes, such as sitemap building, that may require many edit/build/test/debug cycles. After you are done testing, use the forrestbot to "refresh" and "publish" the site.

+ Forrest needs to be run on a machine with a graphical environment. +It will fail in a headless environment when it tries to use FOP to generate the PDF files. +

To use a local Forrest:

+
    +
  • checkout the xml-forrest module (same repository as xml-fop)
    • +
  • checkout the xml-site/targets/fop module (same repository as xml-fop)
    • +
  • you will also need access to a current xml-fop sandbox (you probably already + have one)
    • +
  • cd to xml-forrest
    • +
  • run: build.sh(bat) dist to build forrest
    • +
  • set environment variable FORREST_HOME=~/xml-forrest/build/dist/shbat where ~ is the directory in which xml-forrest is installed (see http://xml.apache.org/forrest/your-project.html for details)
    • +
  • set environment variable PATH=$PATH:$FORREST_HOME/bin
    • +
  • cd to xml-fop directory
    • +
  • run forrest(.bat), which will build the web-site documents in xml-fop/build/site.
    • +
+
+
+ Updating the FOP Web Repository Manually (Deprecated) + The steps in this section should not ordinarily be used. They are documented here for historical reasons, and for emergencies. +
    +
  • Copy (or sym-link) the documents generated by Forrest (in xml-fop/build/site) to xml-site/targets/fop on your local machine.
    • +
  • Commit xml-site/targets/fop.
    • +
+
+
+ + -- 2.39.5