From 6c9968f31e0d1981c5317d2de4b261f85a4e61ee Mon Sep 17 00:00:00 2001
From: Mark Craig <mark.craig@forgerock.com>
Date: Tue, 26 Mar 2013 11:23:13 +0000
Subject: [PATCH] CR-1474 Fix for OPENDJ-814: Document improvement to escape characters in make-ldif templates
---
opendj3/src/main/docbkx/shared/man-make-ldif-template.xml | 37 +++++++++++++-----
opendj3/src/main/docbkx/admin-guide/chap-import-export.xml | 7 +++
opends/resource/man/man5/make-ldif.template.5 | 43 ++++++++++++++++++---
3 files changed, 69 insertions(+), 18 deletions(-)
diff --git a/opendj3/src/main/docbkx/admin-guide/chap-import-export.xml b/opendj3/src/main/docbkx/admin-guide/chap-import-export.xml
index ac39961..f28d409 100644
--- a/opendj3/src/main/docbkx/admin-guide/chap-import-export.xml
+++ b/opendj3/src/main/docbkx/admin-guide/chap-import-export.xml
@@ -20,7 +20,7 @@
!
! CCPL HEADER END
!
- ! Copyright 2011-2012 ForgeRock AS
+ ! Copyright 2011-2013 ForgeRock AS
!
-->
<chapter xml:id='chap-import-export'
@@ -85,6 +85,11 @@
data, and on the sample template,
<filename>OpenDJ/config/MakeLDIF/example.template</filename>, and
associated data.</para>
+
+ <para>See <link xlink:href="admin-guide#make-ldif-template-5"
+ xlink:role="http://docbook.org/xlink/role/olink" xlink:show="new"><citetitle
+ >make-ldif.template</citetitle></link> for reference information about
+ template files.</para>
</step>
<step>
<para>Create additional data files for the content in your template to be
diff --git a/opendj3/src/main/docbkx/shared/man-make-ldif-template.xml b/opendj3/src/main/docbkx/shared/man-make-ldif-template.xml
index 87e8384..7a1a5fb 100644
--- a/opendj3/src/main/docbkx/shared/man-make-ldif-template.xml
+++ b/opendj3/src/main/docbkx/shared/man-make-ldif-template.xml
@@ -20,7 +20,7 @@
!
! CCPL HEADER END
!
- ! Copyright 2012 ForgeRock AS
+ ! Copyright 2012-2013 ForgeRock AS
!
-->
<refentry xml:id='make-ldif-template-5'
@@ -30,7 +30,7 @@
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'>
- <info><copyright><year>2012</year><holder>ForgeRock AS</holder></copyright></info>
+ <info><copyright><year>2012-2013</year><holder>ForgeRock AS</holder></copyright></info>
<refmeta>
<refentrytitle>make-ldif.template</refentrytitle><manvolnum>5</manvolnum>
<refmiscinfo class="software">OpenDJ</refmiscinfo>
@@ -56,8 +56,12 @@
define <replaceable>constant-name</replaceable>=<replaceable>value</replaceable>
...
-# Define branches by suffix DN, such as dc=example,dc=com;
-# ou=People,dc=example,dc=com; ou=Groups,dc=example,dc=com; and so on.
+# Define branches by suffix DN, such as the following:
+#
+# dc=example,dc=com
+# ou=People,dc=example,dc=com
+# ou=Groups,dc=example,dc=com
+#
# make-ldif generates the necessary object class definitions and RDNs.
#
# A branch can have subordinateTemplates that define templates to use for
@@ -112,8 +116,12 @@
<para>When specifying attribute values in <command>make-ldif</command>
templates, you can use static text and constants that you have defined,
- enclosing names for constants in brackets,
- <literal>[myConstant]</literal>.</para>
+ enclosing names for constants in brackets, <literal>[myConstant]</literal>.
+ You can use more than one constant per line, as in the following
+ example.</para>
+
+ <programlisting language="ldif"
+ >description: Description for [org] under [suffix]</programlisting>
<para>You can also use two kinds of tags when specifying attribute values.
One kind of tag gets replaced with the value of another attribute in the
@@ -121,22 +129,31 @@
For example, if your template includes definitions for first name and last
name attributes:</para>
- <programlisting>givenName: <first>
+ <programlisting language="ldif">givenName: <first>
sn: <last></programlisting>
<para>Then you can define a mail attribute that uses the values of both
attributes, and an initials attribute that takes the first character
of each.</para>
- <programlisting>mail: {givenName}.{sn}@[myDomain]
+ <programlisting language="ldif">mail: {givenName}.{sn}@[myDomain]
initials: {givenName:1}{sn:1}</programlisting>
<para>The other kind of tag is delimited with <literal><</literal>
and <literal>></literal>, as shown above in the example with
<literal><first></literal> and <literal><last></literal>.
Tag names are not case sensitive. Many tags can take arguments separated
- by colons, <literal>:</literal>, from the tag names within the tag. OpenDJ
- supports the following tags.</para>
+ by colons, <literal>:</literal>, from the tag names within the tag.</para>
+
+ <para>Use backslashes to escape literal start tag characters (<literal
+ >< [ {</literal>) as shown in the following example, and to escape literal
+ end tag characters within tags (<literal>> ] }</literal>).</para>
+
+ <programlisting language="ldif"
+ >scimMail: \{"emails": \[\{"value": "{mail}", "type": "work", "primary": true}]}
+xml: \<id>{uid}\</id></programlisting>
+
+ <para>OpenDJ supports the following tags.</para>
<varlistentry>
<term><DN></term>
diff --git a/opends/resource/man/man5/make-ldif.template.5 b/opends/resource/man/man5/make-ldif.template.5
index 891e0dc..e88b302 100644
--- a/opends/resource/man/man5/make-ldif.template.5
+++ b/opends/resource/man/man5/make-ldif.template.5
@@ -2,12 +2,12 @@
.\" Title: make-ldif.template
.\" Author:
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
-.\" Date: 06/27/2012
+.\" Date: 03/26/2013
.\" Manual: Tools Reference
.\" Source: OpenDJ 2.5.0
.\" Language: English
.\"
-.TH "MAKE\-LDIF\&.TEMPLAT" "5" "06/27/2012" "OpenDJ 2\&.5\&.0" "Tools Reference"
+.TH "MAKE\-LDIF\&.TEMPLAT" "5" "03/26/2013" "OpenDJ 2\&.5\&.0" "Tools Reference"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
@@ -47,8 +47,12 @@
define \fIconstant\-name\fR=\fIvalue\fR
\&.\&.\&.
-# Define branches by suffix DN, such as dc=example,dc=com;
-# ou=People,dc=example,dc=com; ou=Groups,dc=example,dc=com; and so on\&.
+# Define branches by suffix DN, such as the following:
+#
+# dc=example,dc=com
+# ou=People,dc=example,dc=com
+# ou=Groups,dc=example,dc=com
+#
# make\-ldif generates the necessary object class definitions and RDNs\&.
#
# A branch can have subordinateTemplates that define templates to use for
@@ -101,7 +105,17 @@
When specifying attribute values in
\fBmake\-ldif\fR
templates, you can use static text and constants that you have defined, enclosing names for constants in brackets,
-[myConstant]\&.
+[myConstant]\&. You can use more than one constant per line, as in the following example\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+description: Description for [org] under [suffix]
+.fi
+.if n \{\
+.RE
+.\}
.PP
You can also use two kinds of tags when specifying attribute values\&. One kind of tag gets replaced with the value of another attribute in the generated entry\&. Such tags are delimited with braces,
{ }\&. For example, if your template includes definitions for first name and last name attributes:
@@ -137,7 +151,22 @@
<first>
and
<last>\&. Tag names are not case sensitive\&. Many tags can take arguments separated by colons,
-:, from the tag names within the tag\&. OpenDJ supports the following tags\&.
+:, from the tag names within the tag\&.
+.PP
+Use backslashes to escape literal start tag characters (< [ {) as shown in the following example, and to escape literal end tag characters within tags (> ] })\&.
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+scimMail: \e{"emails": \e[\e{"value": "{mail}", "type": "work", "primary": true}]}
+xml: \e<id>{uid}\e</id>
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+OpenDJ supports the following tags\&.
.PP
<DN>
.RS 4
@@ -505,5 +534,5 @@
/path/to/OpenDJ/config/MakeLDIF/example\&.template
.SH "COPYRIGHT"
.br
-Copyright \(co 2012 ForgeRock AS
+Copyright \(co 2012-2013 ForgeRock AS
.br
--
Gitblit v1.10.0