Cheat sheet, assembly changes and infrastructure changes (#108)

* feedback from Smart Docs trainining: integrate dm: tags for bugtracking, add snippets, fix minor template issues
* Create cheat sheet for creating Smart Docs from scratch. Add odt for source and PDF for reading.

---------

Co-authored-by: Tanja Roth <[email protected]>
Co-authored-by: Tom Schraitle <[email protected]>
Co-authored-by: Tom Schraitle <[email protected]>
Co-authored-by: Frank Sundermeyer <[email protected]>
Co-authored-by: Daria Vladykina <[email protected]>

templates/articles/assembly.asm.xml

@@ -50,15 +50,15 @@
       <description>Reference example</description>
     </resource>
   </resources>
-  <!-- remove comment once we have sorted out the GFDL issue with legal -->
-  <!-- Legal notice and other common files -->
-  <!--
-    <resources>
+  <!-- Legal -->
+  <resources>
+    <resource href="../common/legal.xml" xml:id="_legal">
+      <description>Legal Notice</description>
+    </resource>
     <resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl">
-    <description>GNU Free Documentation License</description>
+      <description>GNU Free Documentation License</description>
     </resource>
-    </resources>
-    -->
+  </resources>
   <!-- S T R U C T U R E -->
   <structure renderas="article" xml:id="article-example">
     <merge>
@@ -87,12 +87,20 @@
       <meta name="maintainer" content="Jane Doe"/>
       <!-- ISO date of last update as YYYY-MM-DD -->
       <meta name="updated" content="2023-11-11"/>
-      <meta name="bugtracker"><phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase><phrase role="component">Non-product-specific documentation</phrase><phrase role="product">Smart Docs</phrase><phrase role="assignee">[email protected]</phrase>
-      </meta>
-      <meta name="translation">
-        <!-- enter yes or no for translation --><phrase role="trans">yes</phrase>
-        <!-- enter languages: ar-ar, cs-cz, ... --><phrase role="language">comma-separated list of languages, for example de-de,cs-cz</phrase>
-      </meta>
+      <!-- this does not work yet. Use the dm tags listed below for now
+        <meta name="bugtracker">
+          <phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase>
+          <phrase role="component">Non-product-specific documentation</phrase>
+          <phrase role="product">Smart Docs</phrase>
+          <phrase role="assignee">[email protected]</phrase>
+        </meta>
+        -->
+      <!-- not supported, yet. Use dm: tag for now
+        <meta name="translation">
+        <phrase role="trans">yes</phrase>
+        <phrase role="language">de-de,cs-cz</phrase>
+        </meta>
+        -->
       <!-- enter the platform identifier or a list of
         identifiers, separated by ; -->
       <meta name="architecture" content="x86;power"/>
@@ -101,9 +109,19 @@
       </meta>
       <meta name="title">short title for SEO and social media, max. 55 chars</meta>
       <meta name="description">short description, max. 150 chars</meta>
-      <meta name="social-descr">ultra short description for social media, max 55 chars</meta>
+      <meta name="social-descr">ultrashort description for social media, max 55 chars</meta>
       <!-- suitable category, comma-separated list of categories -->
       <meta name="category" content="Systems Management"/>
+      <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
+        <dm:bugtracker>
+          <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
+          <dm:component>Smart Docs</dm:component>
+          <dm:product>Documentation</dm:product>
+          <dm:assignee>[email protected]</dm:assignee>
+        </dm:bugtracker>
+        <dm:editurl>https://github.com/SUSE/doc-modular/tree/main/articles/</dm:editurl>
+        <dm:translation>no</dm:translation>
+      </dm:docmanager>
       <abstract>
         <para>
           Provide a short intro to your article here.
@@ -125,10 +143,9 @@
     <module resourceref="_reference-example" renderas="section"/>
     <module resourceref="_glue-more-info" renderas="section"/>
     <module resourceref="_glue-whats-next" renderas="section"/>
-    <!-- pull in one module and nest another module that appears as a child
-      <module resourceref="_my_envelope" renderas="section">
-      <module resourceref="_gfdl" renderas="section"/>
-      </module>
-      -->
+    <module resourceref="_legal"/>
+    <module resourceref="_gfdl">
+      <output renderas="appendix"/>
+    </module>
   </structure>
 </assembly>

templates/common/legal.xml

@@ -0,0 +1 @@
+../../common/legal.xml

templates/snippets/snippet_warning.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE warning
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<warning
+  version="5.2" xmlns="http://docbook.org/ns/docbook"
+  xmlns:xi="http://www.w3.org/2001/XInclude"
+  xmlns:xlink="http://www.w3.org/1999/xlink">
+  <title>Foobar</title>
+  <para>Lorem ipsum</para>
+</warning