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 text­based 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 <itemizedlist>, type in <item, and you should see a drop down entry. Select it, press the Tab key, and you will see something like the following: <itemizedlist> <listitem> < </listitem> </itemizedlist> 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 upgrade­guide.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: <!­­ ! CCPL HEADER START ! ! This work is licensed under the Creative Commons ! Attribution­NonCommercial­NoDerivs 3.0 Unported License. ! To view a copy of this license, visit ! http://creativecommons.org/licenses/by­nc­nd/3.0/ ! or send a letter to Creative Commons, 444 Castro Street, ! Suite 900, Mountain View, California, 94041, USA. ! ! You can also obtain a copy of the license at ! src/main/resources/legal­notices/CC­BY­NC­ND.txt. ! See the License for the specific language governing permissions ! and limitations under the License. ! ! If applicable, add the following below this CCPL HEADER, with the fields ! enclosed by brackets "[]" replaced with your own identifying information: ! Portions Copyright [yyyy] [name of copyright owner] ! ! CCPL HEADER END ! ! Copyright 2011­2013 ForgeRock AS ! ­­> 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: <chapter xml:id=’file­name’ xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en' xmlns:xsi='http://www.w3.org/2001/XMLSchema­instance' xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd' xmlns:xlink='http://www.w3.org/1999/xlink' xmlns:xinclude='http://www.w3.org/2001/XInclude'> <title>Chapter Title</title> <section> </section> </chapter> <appendix xml:id=”file­name”> xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en' xmlns:xsi='http://www.w3.org/2001/XMLSchema­instance' xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd' xmlns:xlink='http://www.w3.org/1999/xlink' xmlns:xinclude='http://www.w3.org/2001/XInclude'> <title>Appendix Title</title> <section> </section> </appendix> Troubleshooting Appendices There are a couple of identifiers that troubleshooting has that are unique: <appendix xml:id='appendix­troubleshooting' xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en' xmlns:xsi='http://www.w3.org/2001/XMLSchema­instance' xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd' xmlns:xlink='http://www.w3.org/1999/xlink' xmlns:xinclude='http://www.w3.org/2001/XInclude'> <title>Troubleshooting XXX</title> <para>This appendix helps you through some basic debugging and troubleshooting during the XX process.</para> <quandaset xml:iid="solutions­to­common­issues" defaultlabel="qanda"> <title>Solutions to Common Issues</title> <para>This section provides information for possible issues you may encounter during XX.</para> <qandadiv xml:id="troubleshooting­openam"> <title>OpenAM</title> <question> <para>Put the question here.</para> </question> <answer> <para>Add the response here.</para> </answer> </qandadiv> </quandaset> </appendix> 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: <section xml:id=”file­name”> xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en' xmlns:xsi='http://www.w3.org/2001/XMLSchema­instance' xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd' xmlns:xlink='http://www.w3.org/1999/xlink' xmlns:xinclude='http://www.w3.org/2001/XInclude'> <title>Section Title</title> </section> Different Section Types Apart from the troubleshooting section types there are a few other section types that can be added. Sections <section xml:id=”section­name”> <title>Section Title</title> </section> Procedures <procedure xml:id=”procedure­name”> <title>Procedure Title</title> <para>Introductory sentence</para> <step> <para></para> </step> </procedure> Examples <example xml:id=”example­name”> <title>Example Title</title> <orderedlist numeration="arabic"> <listitem> <para></para> </listitem> </orderedlist> </example> Different List Types You can create several different list types, depending on if you want the list bulleted or numbered. Bulleted List <itemizedlist> <listitem> <para></para> </listitem> </itemizedlist> Numbered List <orderedlist numeration="arabic"> <listitem> <para></para> </listitem> </orderedlist> You can insert graphics into the document: The following template works with screenshots: <para>Text here</para> <screen>command result</screen> <para>Text here</para> The <para></para> should not include the <screen></screen>, they should always be treated separately. This template works with graphics, such as diagrams: <mediaobject xml:id="figure­graphic­name"> <alt> </alt> <imageobject> <imagedata fileref="images/graphic­name.png" format="PNG" /> </imageobject> <textobject><para>Your description of what it is.</para></textobject> </mediaobject> 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 opendj­ldap­sdk/src/site/site.xml opendj­ldap­sdk/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 chap­custom.xml chap­intro.xml chap­legacy.xml chap­patches.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 *­doc­source 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.