shared.sec-formatting-conventions.xml Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of doc-common-content

This common Open Identity Platform Communitycontent includes text and images in formats suitable for inclusion in core documentation.

There is a newer version: 2.2.2

Show newest version

<?xml version="1.0" encoding="UTF-8"?>
<!--
  ! 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.
  !
  ! 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-2015 ForgeRock AS.
  !
-->
 <section xml:id="formatting-conventions"
          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'>
 <title>Formatting Conventions</title>

 <para>
  Most examples in the documentation are created in GNU/Linux or Mac OS X
  operating environments.

  If distinctions are necessary between operating environments,
  examples are labeled with the operating environment name in parentheses.

  To avoid repetition file system directory names are often given
  only in UNIX format as in <filename>/path/to/server</filename>,
  even if the text applies to <filename>C:\path\to\server</filename> as well.
 </para>

 <para>
  Absolute path names usually begin with the placeholder
  <filename>/path/to/</filename>.

  This path might translate to <filename>/opt/</filename>,
  <filename>C:\Program Files\</filename>, or somewhere else on your system.
 </para>

 <para>
  Command line, terminal sessions are formatted as follows:
 </para>

 <screen>$ <userinput>echo $JAVA_HOME</userinput>
<computeroutput>/path/to/jdk</computeroutput></screen>

 <para>
  Command output is sometimes formatted for narrower, more readable output
  even though formatting parameters are not shown in the command.
  In the following example,
  the query string parameter <literal>_prettyPrint=true</literal> is omitted
  and some of the output is replaced with an ellipsis (<literal>...</literal>):
 </para>

 <screen>
$ <userinput>curl https://bjensen:[email protected]:8443/users/newuser</userinput>
<computeroutput>{
  "_rev" : "000000005b337348",
  "_id" : "newuser",
  ...
}</computeroutput>
 </screen>

 <para>
  Program listings are formatted as follows:
 </para>

 <programlisting language="java">
class Test {
    public static void main(String [] args)  {
        System.out.println("This is a program listing.");
    }
}
 </programlisting>
</section>