i. Our documents are created in DocBook format. You can set up such documents in an IDE such as IntelliJ, Eclipse, or NetBeans. You can even set up documents in textbased editors such as vi or Emacs. ii. If you use an IDE, make sure to include the latest available stable DocBook 5.x schemas from www.docbook.org/schemas. Pay particular attention to the XML Schema files (in .xsd format). Shortly, you’ll see entries such as
xsi:schemaLocation=’http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd
For such entries, you will want to configure the IDE to redirect this noted URLs to stable downloaded versions of these files in your local directory. (Imports may bring them into Cache/ subdirectories, which may not be stable.) For example, in IntelliJ, navigate to IntelliJ IDEA > Preferences. In the left hand pane, you will see Project Settings. Navigate to Schemas and DTDs and made sure to point the noted URLs to appropriate files, as shown.
iii. If you use an IDE, take advantage of its features. Each IDE will have some form of command completion that will allow you to set up appropriate tags. For example, if you aren’t sure what follows an 1. Add the new doc directory to the doc area. If you do not want to commit all of the files simultaneously, commit the directory. All existing files in the directory will be committed when the directory is committed if it is not empty. $ svn add upgradeguide.xml (You can also perform the same task from an IDE such as IntelliJ.) 2. Setup the index.xml file and keep it open as you create files for the new document. This includes the name of all the files that will be part of the build (preface, chapters, appendices). The Shared files in the preface will not need to be added to the index.xml file since they are in the preface.xml file. 3. Create the preface, adding the shared files at the bottom. Copying an existing preface from another doc and then updating it is an easy way to make sure the template is followed. Add basic information about the document. If you don’t know yet, make sure to come back and add it after you have completed the document. 4. Create new files for each chapter. You can do this all at once or one by one as you complete a chapter. Make sure to add the file names to the index file, or to update it if you changed the name of any of your files. Make sure you use the same header in each file. If you decide to start from scratch instead of copying an existing file for any of your new files, make sure to copy the header from one of the existing files. Every file needs to have this header at the top (internal docs won’t use the Creative Commons license) after the following basic comments: The copyright notice is important; whether it uses ForgeRockAS or ForgeRock Inc is still in discussion. The following are the opening and closing identifies for different file types: Troubleshooting Appendices There are a couple of identifiers that troubleshooting has that are unique: Share files Before you update these, make sure that the changes are for all files; if they only pertain to a couple of guides, do not make changes to the shared area: Different Section Types Apart from the troubleshooting section types there are a few other section types that can be added. Sections Procedures Examples Different List Types You can create several different list types, depending on if you want the list bulleted or numbered. Bulleted List Numbered List You can insert graphics into the document: The following template works with screenshots: The This template works with graphics, such as diagrams: In many cases, the image may appear as the wrong size for the document as processed. To address the issue, you may need to use a tool like Mac Preview or The GIMP to adjust the size of the image. Per this PNG density with mogrify blog post, images of 5 inches with a dpi of 160 and 10 cm with a dpi of 140 have worked in the past. 5. Add the new doc to site.xml and docs.xml. This will add them to the main docs page for each project. site.xml adds the doc to the left menu docs.xml adds the different versions of the doc to the main site (e.g., epub, pdf, html...) File locations: OpenAM trunk/openam/src/site/site.xml trunk/openam/src/site/xdoc/docs.xml OpenIDM trunk/src/site/site.xml trunk/src/site/xdoc/docs.xml OpenDJ opendjldapsdk/src/site/site.xml opendjldapsdk/src/site/xdoc/docs.xml OpenIG trunk/src/site/site.xml trunk/src/site/xdoc/docs.xml 6. For the review, add files in the directory. Do not commit the files until the review is complete. You can add the $ svn add chapcustom.xml chapintro.xml chaplegacy.xml chappatches.xml 7. You will not be able to commit the directory until all files within the directory have been added, and you cannot commit files until the directory is committed. ALL files in the directory will be committed when the directory is committed. Remember to commit the site.xml and docs.xml files. 8. You may want to process the new file into publishable formats such as PDF or HTML. The pom.xml files in the *documentation directories should be configured to help a command known as Maven (mvn) process those files. Generally, you’ll want to navigate to the applicable *docsource directory, and then build the documents with a command such as: # mvn Dcheckstyle.skip=true DskipTest=true clean site It is possible to build just one file; it is sometimes preferred for reviews, so people reviewing your work do not have to wade through a lot of extraneous information. For example, the following command builds just the chapminione.xml file as a PDF: # mvn DdocumentSrcName=chapminione.xml Dinclude=pdf clean site Just be aware that the filename of the document will be taken from the index.xml file in the same directory. For example, if the chapminione.xml file is in the directory of an adminguide, the title would read: Even though the output PDF includes just the contents of the chapminione.xml chapter that you’ve just created.