Merge branch 'new-templates' into 'master'

New templates

See merge request GNOME/yelp-tools!4

9 files changed, 509 insertions, 10 deletions

diff --git a/templates/Makefile.am b/templates/Makefile.am
index d4bbb75..1535f3a 100644
--- a/templates/Makefile.am
+++ b/templates/Makefile.am
@@ -1,4 +1,12 @@
 tmpldir = $(datadir)/yelp-tools/templates
-tmpl_DATA = task.page
+tmpl_DATA = 		\
+	concept.duck	\
+	concept.page	\
+	guide.duck	\
+	guide.page	\
+	reference.duck	\
+	reference.page	\
+	task.duck	\
+	task.page
 
 EXTRA_DIST = $(tmpl_DATA)
diff --git a/templates/concept.duck b/templates/concept.duck
new file mode 100644
index 0000000..c349e88
--- /dev/null
+++ b/templates/concept.duck
@@ -0,0 +1,47 @@
+@ducktype/1.0
+[-] yelp-tmpl-desc Explanation of a concept or background information
+
+= @TITLE@
+  [topic .concept version=1.1]
+
+[--
+  Recommended statuses: stub incomplete draft outdated review candidate final
+  Remove version attributes you don't use.
+--]
+@revision[version=0.1 docversion=0.1 pkgversion=0.1 date=@DATE@ status=stub]
+
+@credit[author copyright]
+  @name @NAME@
+  @email @EMAIL@
+  @years @YEAR@
+
+[--
+  This puts a link to this topic on the index page.
+  Change the xref to link it from another guide.
+--]
+@link[guide >index]
+
+[--
+  Think about whether other pages should be in the seealso list.
+  The target page will automatically get a seealso link back.
+@link[seealso >someotherid]
+--]
+
+[--
+  Think about whether external resources should be in the seealso
+  list. These require a title.
+@link[seealso >>http://someurl]
+  @title Link title
+--]
+
+@desc Write a short page description here.
+
+@keywords comma-separated list, of keywords, for search
+
+
+Provide as many paragraphs, lists, or media as necessary to explain.
+
+[list]
+. Next steps
+* Optionally, links to other things the user might do now.
+* But consider using seealso and other info links instead.
diff --git a/templates/concept.page b/templates/concept.page
new file mode 100644
index 0000000..92fbbb8
--- /dev/null
+++ b/templates/concept.page
@@ -0,0 +1,52 @@
+<?yelp-tmpl-desc Explanation of a concept or background information?>
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="concept" version="1.1"
+      id="@ID@">
+  <info>
+    <!--
+        Recommended statuses: stub incomplete draft outdated review candidate final
+        Remove version attributes you don't use.
+    -->
+    <revision version="0.1" docversion="0.1" pkgversion="0.1" date="@DATE@" status="stub"/>
+
+    <credit type="author copyright">
+      <name>@NAME@</name>
+      <email>@EMAIL@</email>
+      <years>@YEAR@</years>
+    </credit>
+
+    <!--
+        This puts a link to this topic on the index page.
+        Change the xref to link it from another guide.
+    -->
+    <link type="guide" xref="index"/>
+
+    <!--
+        Think about whether other pages should be in the seealso list.
+        The target page will automatically get a seealso link back.
+    <link type="seealso" xref="someotherid"/>
+    -->
+
+    <!--
+        Think about whether external resources should be in the seealso
+        list. These require a title.
+    <link type="seealso" href="http://someurl">
+      <title>Link title</title>
+    </link>
+    -->
+
+    <desc>Write a short page description here.</desc>
+
+    <keywords>comma-separated list, of keywords, for search</keywords>
+  </info>
+
+  <title>@TITLE@</title>
+
+  <p>Provide as many paragraphs, lists, or media as necessary to explain.</p>
+
+  <list>
+    <title>Next steps</title>
+    <item><p>Optionally, links to other things the user might do now.</p></item>
+    <item><p>But consider using seealso and other info links instead.</p></item>
+  </list>
+</page>
diff --git a/templates/guide.duck b/templates/guide.duck
new file mode 100644
index 0000000..61cd746
--- /dev/null
+++ b/templates/guide.duck
@@ -0,0 +1,49 @@
+@ducktype/1.0
+[-] yelp-tmpl-desc Navigational glue for Mallard documents
+
+= @TITLE@
+  [guide version=1.1]
+
+[--
+  Recommended statuses: stub incomplete draft outdated review candidate final
+  Remove version attributes you don't use.
+--]
+@revision[version=0.1 docversion=0.1 pkgversion=0.1 date=@DATE@ status=stub]
+
+@credit[author copyright]
+  @name @NAME@
+  @email @EMAIL@
+  @years @YEAR@
+
+[--
+  This puts a link to this topic on the index page.
+  Change the xref to link it from another guide.
+--]
+@link[guide >index]
+
+[--
+  Think about whether other pages should be in the seealso list.
+  The target page will automatically get a seealso link back.
+@link[seealso >someotherid]
+--]
+
+[--
+  Think about whether external resources should be in the seealso
+  list. These require a title.
+@link[seealso >>http://someurl]
+  @title Link title
+--]
+
+@desc Write a short page description here.
+
+@keywords comma-separated list, of keywords, for search
+
+
+Optionally, an introductory paragraph.
+
+[--
+  The links element is implicit, but you might want to add one
+  explicitly if you want to do link grouping or styles.
+[links topic .STYLE groups="GROUPS"]
+  . Optional title
+--]
diff --git a/templates/guide.page b/templates/guide.page
new file mode 100644
index 0000000..894b276
--- /dev/null
+++ b/templates/guide.page
@@ -0,0 +1,55 @@
+<?yelp-tmpl-desc Navigational glue for Mallard documents?>
+<page xmlns="http://projectmallard.org/1.0/"
+      type="guide" version="1.1"
+      id="@ID@">
+  <info>
+    <!--
+        Recommended statuses: stub incomplete draft outdated review candidate final
+        Remove version attributes you don't use.
+    -->
+    <revision version="0.1" docversion="0.1" pkgversion="0.1" date="@DATE@" status="stub"/>
+
+    <credit type="author copyright">
+      <name>@NAME@</name>
+      <email>@EMAIL@</email>
+      <years>@YEAR@</years>
+    </credit>
+
+    <!--
+        This puts a link to this topic on the index page.
+        Change the xref to link it from another guide.
+    -->
+    <link type="guide" xref="index"/>
+
+    <!--
+        Think about whether other pages should be in the seealso list.
+        The target page will automatically get a seealso link back.
+    <link type="seealso" xref="someotherid"/>
+    -->
+
+    <!--
+        Think about whether external resources should be in the seealso
+        list. These require a title.
+    <link type="seealso" href="http://someurl">
+      <title>Link title</title>
+    </link>
+    -->
+
+    <desc>Write a short page description here.</desc>
+
+    <keywords>comma-separated list, of keywords, for search</keywords>
+  </info>
+
+  <title>@TITLE@</title>
+
+  <p>Optionally, an introductory paragraph.</p>
+
+  <!--
+      The links element is implicit, but you might want to add one
+      explicitly if you want to do link grouping or styles.
+  <links type="topic" style="STYLE" groups="GROUPS">
+    <title>Optional title</title>
+  </links>
+  -->
+
+</page>
diff --git a/templates/reference.duck b/templates/reference.duck
new file mode 100644
index 0000000..0aae96b
--- /dev/null
+++ b/templates/reference.duck
@@ -0,0 +1,90 @@
+@ducktype/1.0
+[-] yelp-tmpl-desc Lists or tables of information for quick lookup
+
+= @TITLE@
+  [topic .reference version=1.1]
+
+[--
+  Recommended statuses: stub incomplete draft outdated review candidate final
+  Remove version attributes you don't use.
+--]
+@revision[version=0.1 docversion=0.1 pkgversion=0.1 date=@DATE@ status=stub]
+
+@credit[author copyright]
+  @name @NAME@
+  @email @EMAIL@
+  @years @YEAR@
+
+[--
+  This puts a link to this topic on the index page.
+  Change the xref to link it from another guide.
+--]
+@link[guide >index]
+
+[--
+  Think about whether other pages should be in the seealso list.
+  The target page will automatically get a seealso link back.
+@link[seealso >someotherid]
+--]
+
+[--
+  Think about whether external resources should be in the seealso
+  list. These require a title.
+@link[seealso >>http://someurl]
+  @title Link title
+--]
+
+@desc Write a short page description here.
+
+@keywords comma-separated list, of keywords, for search
+
+
+Optionally provide introductory text.
+Use terms lists, tables, and bullet lists for reference material.
+
+
+[terms]
+. Example terms list (title optional)
+
+- Term 1
+* Description
+
+- Term 2
+* Terms can have multiple paragraphs.
+
+  [screen]
+  Or any other block element.
+
+- Term 3.1
+- Term 3.2
+* Terms can also have multiple titles.
+
+
+[table]
+. Example table (title optional)
+
+[thead]
+[tr]
+- Column 1
+- Column 2
+
+[tbody]
+[tr]
+* Row 1, column 1
+* Row 1, column 2
+
+[tr]
+* Row 2, column 1
+* Row 2, column 2
+
+
+[list]
+. Example list (title optional)
+
+* Item 1
+
+* Item 2
+  * Subitem 2.1
+  * Subitem 2.2
+
+* Item 3
diff --git a/templates/reference.page b/templates/reference.page
new file mode 100644
index 0000000..c7364ee
--- /dev/null
+++ b/templates/reference.page
@@ -0,0 +1,99 @@
+<?yelp-tmpl-desc Lists or tables of information for quick lookup?>
+<page xmlns="http://projectmallard.org/1.0/"
+      type="topic" style="reference" version="1.1"
+      id="@ID@">
+  <info>
+    <!--
+        Recommended statuses: stub incomplete draft outdated review candidate final
+        Remove version attributes you don't use.
+    -->
+    <revision version="0.1" docversion="0.1" pkgversion="0.1" date="@DATE@" status="stub"/>
+
+    <credit type="author copyright">
+      <name>@NAME@</name>
+      <email>@EMAIL@</email>
+      <years>@YEAR@</years>
+    </credit>
+
+    <!--
+        This puts a link to this topic on the index page.
+        Change the xref to link it from another guide.
+    -->
+    <link type="guide" xref="index"/>
+
+    <!--
+        Think about whether other pages should be in the seealso list.
+        The target page will automatically get a seealso link back.
+    <link type="seealso" xref="someotherid"/>
+    -->
+
+    <!--
+        Think about whether external resources should be in the seealso
+        list. These require a title.
+    <link type="seealso" href="http://someurl">
+      <title>Link title</title>
+    </link>
+    -->
+
+    <desc>Write a short page description here.</desc>
+
+    <keywords>comma-separated list, of keywords, for search</keywords>
+  </info>
+
+  <title>@TITLE@</title>
+
+  <p>Optionally provide introductory text.
+  Use terms lists, tables, and bullet lists for reference material.</p>
+
+  <terms>
+    <title>Example terms list (title optional)</title>
+    <item>
+      <title>Term 1</title>
+      <para>Description</para>
+    </item>
+    <item>
+      <title>Term 2</title>
+      <p>Terms can have multiple paragraphs.</p>
+      <screen>Or any other block element.</screen>
+    </item>
+    <item>
+      <title>Term 3.1</title>
+      <title>Term 3.2</title>
+      <p>Terms can also have multiple titles.</p>
+    </item>
+  </terms>
+
+  <table>
+    <title>Example table (title optional)</title>
+    <thead>
+      <tr>
+        <th>Column 1</th>
+        <th>Column 2</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td>Row 1, column 1</td>
+        <td>Row 1, column 2</td>
+      </tr>
+      <tr>
+        <td>Row 2, column 1</td>
+        <td>Row 2, column 2</td>
+      </tr>
+    </tbody>
+  </table>
+
+  <list>
+    <title>Example list (title optional)</title>
+    <item><p>Item 1</p></item>
+    <item>
+      <p>Item 2</p>
+      <list>
+        <item><p>Subitem 2.1</p></item>
+        <item><p>Subitem 2.2</p></item>
+      </list>
+    </item>
+    <item><p>Item 3</p></item>
+  </list>
+
+</page>
diff --git a/templates/task.duck b/templates/task.duck
new file mode 100644
index 0000000..75c8243
--- /dev/null
+++ b/templates/task.duck
@@ -0,0 +1,63 @@
+@ducktype/1.0
+[-] yelp-tmpl-desc Description of how to accomplish a user task
+
+= @TITLE@
+  [topic .task version=1.1]
+
+[--
+  Recommended statuses: stub incomplete draft outdated review candidate final
+  Remove version attributes you don't use.
+--]
+@revision[version=0.1 docversion=0.1 pkgversion=0.1 date=@DATE@ status=stub]
+
+@credit[author copyright]
+  @name @NAME@
+  @email @EMAIL@
+  @years @YEAR@
+
+[--
+  This puts a link to this topic on the index page.
+  Change the xref to link it from another guide.
+--]
+@link[guide >index]
+
+[--
+  Think about whether other pages should be in the seealso list.
+  The target page will automatically get a seealso link back.
+@link[seealso >someotherid]
+--]
+
+[--
+  Think about whether external resources should be in the seealso
+  list. These require a title.
+@link[seealso >>http://someurl]
+  @title Link title
+--]
+
+@desc Write a short page description here.
+
+@keywords comma-separated list, of keywords, for search
+
+
+Short introductory text: Write a couple sentences about what the
+user is doing here, and why they might want to do it.
+
+[list]
+. Prerequisites
+* Optionally, list things the user needs to know or do first.
+* Use links to other pages whenever they make sense.
+
+[steps]
+. Optional title if different from page title or if prereqs present
+* First step...
+* Second step...
+* Third step...
+
+Optionally, write expected results if non-obvious.
+
+[list]
+. Next steps
+* Optionally, links to other things the user might do now.
+* But consider using seealso and other info links instead.
+
+
diff --git a/templates/task.page b/templates/task.page
index 225aefe..ba7be5f 100644
--- a/templates/task.page
+++ b/templates/task.page
@@ -1,9 +1,13 @@
 <?yelp-tmpl-desc Description of how to accomplish a user task?>
 <page xmlns="http://projectmallard.org/1.0/"
-      type="topic" style="task"
+      type="topic" style="task" version="1.1"
       id="@ID@">
   <info>
-    <revision version="0.1" date="@DATE@" status="stub"/>
+    <!--
+        Recommended statuses: stub incomplete draft outdated review candidate final
+        Remove version attributes you don't use.
+    -->
+    <revision version="0.1" docversion="0.1" pkgversion="0.1" date="@DATE@" status="stub"/>
 
     <credit type="author copyright">
       <name>@NAME@</name>
@@ -11,23 +15,55 @@
       <years>@YEAR@</years>
     </credit>
 
-    <desc></desc>
+    <!--
+        This puts a link to this topic on the index page.
+        Change the xref to link it from another guide.
+    -->
+    <link type="guide" xref="index"/>
+
+    <!--
+        Think about whether other pages should be in the seealso list.
+        The target page will automatically get a seealso link back.
+    <link type="seealso" xref="someotherid"/>
+    -->
+
+    <!--
+        Think about whether external resources should be in the seealso
+        list. These require a title.
+    <link type="seealso" href="http://someurl">
+      <title>Link title</title>
+    </link>
+    -->
+
+    <desc>Write a short page description here.</desc>
+
+    <keywords>comma-separated list, of keywords, for search</keywords>
   </info>
 
   <title>@TITLE@</title>
 
-  <comment>
-    <cite date="@DATE@" href="mailto:@EMAIL@">@NAME@</cite>
-    <p>This assumes the reader knows how to.... By the end of this page,
-    the reader will be able to....</p>
-  </comment>
+  <p>Short introductory text: Write a couple sentences about what the
+  user is doing here, and why they might want to do it.</p>
 
-  <p>Short introductory text...</p>
+  <list>
+    <title>Prerequisites</title>
+    <item><p>Optionally, list things the user needs to know or do first.</p></item>
+    <item><p>Use links to other pages whenever they make sense.</p></item>
+  </list>
 
   <steps>
+    <title>Optional title if different from page title or if prereqs present</title>
     <item><p>First step...</p></item>
     <item><p>Second step...</p></item>
     <item><p>Third step...</p></item>
   </steps>
 
+  <p>Optionally, write expected results if non-obvious.</p>
+
+  <list>
+    <title>Next steps</title>
+    <item><p>Optionally, links to other things the user might do now.</p></item>
+    <item><p>But consider using seealso and other info links instead.</p></item>
+  </list>
+
 </page>