private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery
This document is produced using a combination of maven, git, and docbook. We welcome anyone and everyone to contribute to the content of this book. Below is the information on how to obtain the source of this book and to build it as well as information on how to contribute back to it.
Note: All contributions to this documentation are under the EPL and the copyright is assigned to Mortbay.
You will need:
This project is located at github so if you do not have a GitHub account already you should register for one. You can do that at Github
You can go one of two ways for using git, if you are familiar with SCM's and the command line interface then feel free to install and use git from there. Otherwise we would recommend you use the github client itself as it will help with some of the workflow involved with working with git.
We build the project with maven 3 which can be found at Apache Maven
First you need to obtain the source of the documentation project.
Clone the repository:
$ git clone https://github.com/jetty-project/jetty-documentation.git
You will now have a local directory with all of the jetty-documentation. Now we move on to building it.
$ cd jetty-documentation $ mvn install
While maven is running you may see a lot of files being downloaded. If you are not familiar with maven, then what you are seeing is maven setting up the execution environment for generating the documentation. This build should produce xhtml, as well as any other output formats that we are working with as time goes on. The downloads are all of the java dependencies that are required to make this build work. After a while the downloading will stop and you'll see the execution of the docbkx-maven-plugin.
[INFO] --- docbkx-maven-plugin:2.0.13:generate-xhtml (documentation identifier) @ jetty-documentation --- [INFO] Processing input file: jetty.xml [INFO] Dumping to /home/jesse/src/projects/jetty/jetty-documentation/target/docbkx/generated/(gen)jetty.xml [INFO] Applying customization parameters [INFO] Chunking output. <?xml version="1.0" encoding="UTF-8"?> [INFO] See /home/jesse/src/projects/jetty/jetty-documentation/target/docbkx/xhtml/jetty for generated file(s) [INFO] Executing tasks [INFO] Executed tasks
The build is finished once you see a message akin to this:
[INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 7.014s [INFO] Finished at: Tue Oct 25 14:15:37 CDT 2011 [INFO] Final Memory: 14M/229M [INFO] ------------------------------------------------------------------------
You may now open your web browser and browse to the first page of the html output to see what you have produced! Generally you can do this with File -> Open File -> which will open a file system browsing screen, navigate to your jetty-documentation directory and then further into target/docbkx/xhtml/jetty/jetty.html which is the first page of the produced documentation.
Note: if the build is broken, feel free to notify us.
Now that you have built the documentation, you want to edit it and make some changes. We'll now have to take a bit of as step back and look at how git and github works. In the above example you have cloned directly from our canonical documentation repository. Obviously we can not allow anyone immediate access to this repository so you must make a fork of it for your own and then issue back pull requests to build up documentation karma. In English that means that you would go to the url of the documentation in github:
When you are on this page you will see a little button called 'Fork' which you can click and you will be taken back to your main page on github where you have a new repository. When you checkout this repository you are free to commit to your heart's delight all the changes you so direly wish to see in the Jetty documentation. You can clone it to your local machine and build it the same way as above. So let's start small with a little example. Find some paragraph in the documentation that you think needs changed. Locate that in the local checkout and make the change. Now follow the process to push that change back into Jetty proper. Do make sure the change works and the build isn't broken though so make sure you run maven and check the output. Then commit the change.
$ git commit -m "Tweaked the introduction to fix a horrid misspelled word." src/docbkbx/topics/introduction/topic.xml
This will commit the change in your local repository. You can then push the change up to your repository on github.
$ git push
Now you'll see some output showing that your change has been propagated to your repository on github. In fact if you navigate to that repository at the top of the files list you should see your comment there. Success, your change is now positioned for notifying us about it! If you click on the commit message itself you'll be taken to a screen that shows what files were changed in that commit. In the upper right corner is a button for 'Pull Request'. When you select this and follow the workflow we will then be notified of your contribution and will be able to apply it to our git repository upon review.
Thats it! You have successfully contributed to the documentation efforts of the Jetty project. After enough of these sorts of contributions and building up good community karma, you may be asked to join us as a commiter on the documentation.
Below is list of conventions that should be followed when developing documentation within this framework. These are not set in stone and should be updated as we learn more.
We have an xmlfresh maven plugin that reformats the code to the standards for the project. This is to prevent wide spread merge conflict between commits. The line wrap is set to 120 and the indent is 2 spaces, never tab characters. There are a handful of tags that render inline to the para tags, these are found in the maven configuration of the xmlfresh-maven-plugin.
Critically important for being able to generate url's that can be used in a persistent fashion. Without xml:id's the chapters and sections will have generated id which are rooting in obscure location based voodoo. A url using these 'e12c8673' type links will not be durable across generations of the documentation. These xml:id's need to be used on chapters and sections two deep, and anywhere that you intend to cross link deeper.
The xml:id values go into a global namespace so they must be unique across the entire document or the last example will win and any cross links will go there. We will have a maven plugin that will fail the build on detecting this soon.
in general differences in functionality within a major should go into nested sections and use titles like 'Prior to: ##' or 'In version: ##'
each xml file should contain the license block that exists in the jetty.xml file and a copy has been added to the bottom of this page as well for reference. It should occupy the second through eighteeth lines while the first line should be the xml descriptor.
<?xml version="1.0" encoding="utf-8"?> <!-- // ======================================================================== // Copyright (c) 1995-2012 Mort Bay Consulting Pty. Ltd. // ======================================================================== // All rights reserved. This program and the accompanying materials // are made available under the terms of the Eclipse Public License v1.0 // and Apache License v2.0 which accompanies this distribution. // // The Eclipse Public License is available at // http://www.eclipse.org/legal/epl-v10.html // // The Apache License v2.0 is available at // http://www.opensource.org/licenses/apache2.0.php // // You may elect to redistribute this code under either of these licenses. // ======================================================================== -->
Some admonition examples:
A note about the previous case to be aware of.
Important notes are marked with an icon.
Tips that make your life easier.
Places where you have to be careful what you are doing.
Where extreme care has to be taken. Data corruption or other nasty things may occur if these warnings are ignored.