From cd917e88f5718eead826c896864cfe85cd3d301b Mon Sep 17 00:00:00 2001
From: Rickard Green <rickard@erlang.org>
Date: Wed, 17 Dec 2014 21:07:55 +0100
Subject: Support for <do> and <dont> doc tags

---
 lib/erl_docgen/priv/css/otp_doc.css       | 28 +++++++++++++++++++++++++++-
 lib/erl_docgen/priv/dtd/application.dtd   |  2 +-
 lib/erl_docgen/priv/dtd/book.dtd          |  4 ++--
 lib/erl_docgen/priv/dtd/chapter.dtd       |  4 ++--
 lib/erl_docgen/priv/dtd/common.dtd        |  2 ++
 lib/erl_docgen/priv/dtd/common.refs.dtd   |  6 +++---
 lib/erl_docgen/priv/dtd/part.dtd          |  2 +-
 lib/erl_docgen/priv/dtd/report.dtd        |  4 +++-
 lib/erl_docgen/priv/xsl/db_html.xsl       | 30 ++++++++++++++++++++++++++++++
 lib/erl_docgen/priv/xsl/db_man.xsl        | 24 +++++++++++++++++++++++-
 lib/erl_docgen/priv/xsl/db_pdf.xsl        | 25 +++++++++++++++++++++++++
 lib/erl_docgen/priv/xsl/db_pdf_params.xsl | 27 +++++++++++++++++++++++++++
 12 files changed, 146 insertions(+), 12 deletions(-)

(limited to 'lib/erl_docgen')

diff --git a/lib/erl_docgen/priv/css/otp_doc.css b/lib/erl_docgen/priv/css/otp_doc.css
index c56de378f4..2aae87a759 100644
--- a/lib/erl_docgen/priv/css/otp_doc.css
+++ b/lib/erl_docgen/priv/css/otp_doc.css
@@ -66,7 +66,7 @@ a:visited      { color: blue; text-decoration: none }
 span.bold_code   { font-family: Courier, monospace; font-weight: bold }
 span.code        { font-family: Courier, monospace; font-weight: normal }
 
-.note, .warning {
+.note, .warning, .do, .dont {
   border: solid black 1px;
   margin: 1em 3em;
 }
@@ -96,6 +96,32 @@ span.code        { font-family: Courier, monospace; font-weight: normal }
   font-size: 90%;
   padding: 5px 10px;
 }
+.do .label {
+  background: #30d42a;
+  color: white;
+  font-weight: bold;
+  padding: 5px 10px;
+}
+.do .content {
+  background: #eafeea;
+  color: black;
+  line-height: 120%;
+  font-size: 90%;
+  padding: 5px 10px;
+}
+.dont .label {
+  background: #C00;
+  color: white;
+  font-weight: bold;
+  padding: 5px 10px;
+}
+.dont .content {
+  background: #FFF0F0;
+  color: black;
+  line-height: 120%;
+  font-size: 90%;
+  padding: 5px 10px;
+}
 .example {
   background-color:#eeeeff;
   padding: 0px 10px;
diff --git a/lib/erl_docgen/priv/dtd/application.dtd b/lib/erl_docgen/priv/dtd/application.dtd
index 8a1e8832ec..fcadaced72 100644
--- a/lib/erl_docgen/priv/dtd/application.dtd
+++ b/lib/erl_docgen/priv/dtd/application.dtd
@@ -24,6 +24,6 @@
 %common.header;
 
 <!ELEMENT application         (header,description?,include+) >
-<!ELEMENT description	      (%block;|quote|br|marker|warning|note)* >
+<!ELEMENT description	      (%block;|quote|br|marker|warning|note|dont|do)* >
 <!ELEMENT include             EMPTY >
 <!ATTLIST include             file CDATA #REQUIRED>
diff --git a/lib/erl_docgen/priv/dtd/book.dtd b/lib/erl_docgen/priv/dtd/book.dtd
index bb89a6d255..ef723a9eed 100644
--- a/lib/erl_docgen/priv/dtd/book.dtd
+++ b/lib/erl_docgen/priv/dtd/book.dtd
@@ -38,7 +38,7 @@
 
 <!ELEMENT pagetext	      (#PCDATA) >
 <!ELEMENT preamble	      (contents?,preface?) >
-<!ELEMENT preface	      (title?,(%block;|quote|br|marker|warning|note|table)*) >
+<!ELEMENT preface	      (title?,(%block;|quote|br|marker|warning|note|dont|do|table)*) >
 
 <!ELEMENT insidecover         (#PCDATA|br|theheader|vfill|vspace|tt|bold|
 			       include)* >
@@ -67,7 +67,7 @@
 <!ELEMENT onepart             (title?,description?,include+) >
 <!ATTLIST onepart             lift (yes|no) "no" >
 
-<!ELEMENT description	      (%block;|quote|br|marker|warning|note)* >
+<!ELEMENT description	      (%block;|quote|br|marker|warning|note|dont|do)* >
 
 <!ELEMENT include             EMPTY >
 <!ATTLIST include             file CDATA #REQUIRED>
diff --git a/lib/erl_docgen/priv/dtd/chapter.dtd b/lib/erl_docgen/priv/dtd/chapter.dtd
index eb2c96b04f..4beff6cc54 100644
--- a/lib/erl_docgen/priv/dtd/chapter.dtd
+++ b/lib/erl_docgen/priv/dtd/chapter.dtd
@@ -29,8 +29,8 @@
 
 <!-- Structure -->
 
-<!ELEMENT chapter             (header,(%block;|quote|warning|note|br|
+<!ELEMENT chapter             (header,(%block;|quote|warning|note|dont|do|br|
                                image|marker|table)*,section+) >
 <!ELEMENT section             (marker*,title,
-                               (%block;|quote|warning|note|br|image|marker|
+                               (%block;|quote|warning|note|dont|do|br|image|marker|
                                 table|section)*) >
diff --git a/lib/erl_docgen/priv/dtd/common.dtd b/lib/erl_docgen/priv/dtd/common.dtd
index f999ef8ea4..92d814e0f1 100644
--- a/lib/erl_docgen/priv/dtd/common.dtd
+++ b/lib/erl_docgen/priv/dtd/common.dtd
@@ -34,6 +34,8 @@
 <!ELEMENT quote               (p)* >
 <!ELEMENT warning             (%block;|quote|br|marker)* >
 <!ELEMENT note                (%block;|quote|br|marker)* >
+<!ELEMENT dont                (%block;|quote|br|marker)* >
+<!ELEMENT do                  (%block;|quote|br|marker)* >
 <!ELEMENT c                   (#PCDATA) >
 <!ELEMENT em                  (#PCDATA|c)* >
 
diff --git a/lib/erl_docgen/priv/dtd/common.refs.dtd b/lib/erl_docgen/priv/dtd/common.refs.dtd
index 93592607df..a08b9e89d4 100644
--- a/lib/erl_docgen/priv/dtd/common.refs.dtd
+++ b/lib/erl_docgen/priv/dtd/common.refs.dtd
@@ -24,7 +24,7 @@
 <!ENTITY % common.header SYSTEM "common.header.dtd" >
 %common.header;
 
-<!ELEMENT description         (%block;|quote|br|marker|warning|note)* >
+<!ELEMENT description         (%block;|quote|br|marker|warning|note|dont|do)* >
 <!ELEMENT funcs               (func)+ >
 <!ELEMENT func                (name+,type_desc*,fsummary,type?,desc?) >
 <!-- ELEMENT name is defined in each ref dtd -->
@@ -34,12 +34,12 @@
                                name_i CDATA #IMPLIED>
 <!ELEMENT v                   (#PCDATA) >
 <!ELEMENT d                   (#PCDATA|c|em)* >
-<!ELEMENT desc                (%block;|quote|br|marker|warning|note|anno)* >
+<!ELEMENT desc                (%block;|quote|br|marker|warning|note|dont|do|anno)* >
 <!ELEMENT authors             (aname,email)+ >
 <!ELEMENT aname               (#PCDATA) >
 <!ELEMENT email               (#PCDATA) >
 <!ELEMENT section             (marker*,title,(%block;|quote|br|marker|
-                               warning|note)*) >
+                               warning|note|dont|do)*) >
 <!ELEMENT datatypes           (datatype)+ >
 <!ELEMENT datatype            (name+,desc?) >
 <!ELEMENT type_desc           (#PCDATA) >
diff --git a/lib/erl_docgen/priv/dtd/part.dtd b/lib/erl_docgen/priv/dtd/part.dtd
index 3f97199042..79f68c415d 100644
--- a/lib/erl_docgen/priv/dtd/part.dtd
+++ b/lib/erl_docgen/priv/dtd/part.dtd
@@ -24,6 +24,6 @@
 %common.header;
 
 <!ELEMENT part                (header,description?,include+) >
-<!ELEMENT description         (%block;|quote|br|marker|warning|note)* >
+<!ELEMENT description         (%block;|quote|br|marker|warning|note|dont|do)* >
 <!ELEMENT include             EMPTY >
 <!ATTLIST include             file CDATA #REQUIRED>
diff --git a/lib/erl_docgen/priv/dtd/report.dtd b/lib/erl_docgen/priv/dtd/report.dtd
index 3d07e6e5a7..eb463f8867 100644
--- a/lib/erl_docgen/priv/dtd/report.dtd
+++ b/lib/erl_docgen/priv/dtd/report.dtd
@@ -48,7 +48,7 @@
 <!ELEMENT file                (#PCDATA) >
 
 <!ELEMENT section             (marker*,title,
-                               (%block;|quote|warning|note|br|image|marker|
+                               (%block;|quote|warning|note|dont|do|br|image|marker|
                                 table|section)*) >
 <!ELEMENT p                   (%inline;|index)* >
 <!ELEMENT pre                 (#PCDATA|seealso|url|input)* >
@@ -58,6 +58,8 @@
 <!ELEMENT quote               (p)* >
 <!ELEMENT warning             (%block;|quote|br|image|marker|table)* >
 <!ELEMENT note                (%block;|quote|br|image|marker|table)* >
+<!ELEMENT dont                (%block;|quote|br|image|marker|table)* >
+<!ELEMENT do                  (%block;|quote|br|image|marker|table)* >
 <!ELEMENT i                   (#PCDATA|b|c|em)* >
 <!ELEMENT b                   (#PCDATA|i|c|em)* >
 <!ELEMENT c                   (#PCDATA) >
diff --git a/lib/erl_docgen/priv/xsl/db_html.xsl b/lib/erl_docgen/priv/xsl/db_html.xsl
index ab5f24c406..3b390f48fb 100644
--- a/lib/erl_docgen/priv/xsl/db_html.xsl
+++ b/lib/erl_docgen/priv/xsl/db_html.xsl
@@ -952,6 +952,36 @@
     </div>
   </xsl:template>
 
+  <!-- Do -->
+  <xsl:template match="do">
+    <xsl:param name="chapnum"/>
+    <div class="do">
+      <div class="label">Do</div>
+      <div class="content">
+        <p>
+          <xsl:apply-templates>
+            <xsl:with-param name="chapnum" select="$chapnum"/>
+          </xsl:apply-templates>
+        </p>
+      </div>
+    </div>
+  </xsl:template>
+
+  <!-- Dont -->
+  <xsl:template match="dont">
+    <xsl:param name="chapnum"/>
+    <div class="dont">
+      <div class="label">Don't</div>
+      <div class="content">
+        <p>
+          <xsl:apply-templates>
+            <xsl:with-param name="chapnum" select="$chapnum"/>
+          </xsl:apply-templates>
+        </p>
+      </div>
+    </div>
+  </xsl:template>
+
  <!-- Paragraph -->
   <xsl:template match="p">
     <p>
diff --git a/lib/erl_docgen/priv/xsl/db_man.xsl b/lib/erl_docgen/priv/xsl/db_man.xsl
index 3bcdd11c35..0caaba560f 100644
--- a/lib/erl_docgen/priv/xsl/db_man.xsl
+++ b/lib/erl_docgen/priv/xsl/db_man.xsl
@@ -543,7 +543,29 @@
     <xsl:text>&#10;</xsl:text>
   </xsl:template>
 
-  <xsl:template match="warning/p | note/p">
+  <!-- Do -->
+  <xsl:template match="do">
+    <xsl:text>&#10;.LP&#10;</xsl:text>
+    <xsl:text>&#10;.RS -4</xsl:text>
+    <xsl:text>&#10;.B&#10;</xsl:text>
+    <xsl:text>Do:</xsl:text>
+    <xsl:text>&#10;.RE</xsl:text>
+    <xsl:apply-templates/>
+    <xsl:text>&#10;</xsl:text>
+  </xsl:template>
+
+  <!-- Dont -->
+  <xsl:template match="dont">
+    <xsl:text>&#10;.LP&#10;</xsl:text>
+    <xsl:text>&#10;.RS -4</xsl:text>
+    <xsl:text>&#10;.B&#10;</xsl:text>
+    <xsl:text>Dont:</xsl:text>
+    <xsl:text>&#10;.RE</xsl:text>
+    <xsl:apply-templates/>
+    <xsl:text>&#10;</xsl:text>
+  </xsl:template>
+
+  <xsl:template match="warning/p | note/p | dont/p | do/p">
     <xsl:variable name="content">
       <xsl:text>&#10;</xsl:text>
       <xsl:apply-templates/>
diff --git a/lib/erl_docgen/priv/xsl/db_pdf.xsl b/lib/erl_docgen/priv/xsl/db_pdf.xsl
index c15b16eb5b..8e7ffddefa 100644
--- a/lib/erl_docgen/priv/xsl/db_pdf.xsl
+++ b/lib/erl_docgen/priv/xsl/db_pdf.xsl
@@ -1138,6 +1138,31 @@
     </fo:block>
   </xsl:template>
 
+  <!-- Do -->
+  <xsl:template match="do">
+    <xsl:param name="partnum"/>
+    <fo:block xsl:use-attribute-sets="do">
+        <fo:block xsl:use-attribute-sets="note-warning-title">
+            <xsl:text>Do:</xsl:text>
+        </fo:block>
+      <xsl:apply-templates>
+        <xsl:with-param name="partnum" select="$partnum"/>
+      </xsl:apply-templates>
+    </fo:block>
+  </xsl:template>
+
+  <!-- Dont -->
+  <xsl:template match="dont">
+    <xsl:param name="partnum"/>
+    <fo:block xsl:use-attribute-sets="dont">
+        <fo:block xsl:use-attribute-sets="note-warning-title">
+            <xsl:text>Don't:</xsl:text>
+        </fo:block>
+      <xsl:apply-templates>
+        <xsl:with-param name="partnum" select="$partnum"/>
+      </xsl:apply-templates>
+    </fo:block>
+  </xsl:template>
 
  <!-- Paragraph -->
   <xsl:template match="p">
diff --git a/lib/erl_docgen/priv/xsl/db_pdf_params.xsl b/lib/erl_docgen/priv/xsl/db_pdf_params.xsl
index 2e3b22acf4..c2d9fb4320 100644
--- a/lib/erl_docgen/priv/xsl/db_pdf_params.xsl
+++ b/lib/erl_docgen/priv/xsl/db_pdf_params.xsl
@@ -289,6 +289,33 @@
     <xsl:attribute name="keep-together.within-page">always</xsl:attribute>
   </xsl:attribute-set>
 
+<xsl:attribute-set name="do">
+    <xsl:attribute name="background-color">#d0fed0</xsl:attribute>
+    <xsl:attribute name="space-after">1em</xsl:attribute>
+    <xsl:attribute name="space-before">2em</xsl:attribute>
+    <xsl:attribute name="text-align">justify</xsl:attribute>
+    <xsl:attribute name="padding-before">1em</xsl:attribute>
+    <xsl:attribute name="padding-after">0.3em</xsl:attribute>
+    <xsl:attribute name="padding-left">0.5em</xsl:attribute>
+    <xsl:attribute name="padding-right">0.5em</xsl:attribute>
+    <xsl:attribute name="margin-left">0.5em</xsl:attribute>
+    <xsl:attribute name="margin-right">0.5em</xsl:attribute>
+    <xsl:attribute name="keep-together.within-page">always</xsl:attribute>
+  </xsl:attribute-set>
+
+<xsl:attribute-set name="dont">
+  <xsl:attribute name="background-color">#ffd6d6</xsl:attribute> 
+    <xsl:attribute name="space-after">1em</xsl:attribute>
+    <xsl:attribute name="space-before">2em</xsl:attribute>
+    <xsl:attribute name="text-align">justify</xsl:attribute>
+    <xsl:attribute name="padding-before">1em</xsl:attribute>
+    <xsl:attribute name="padding-after">0.3em</xsl:attribute>
+    <xsl:attribute name="padding-left">0.5em</xsl:attribute>
+    <xsl:attribute name="padding-right">0.5em</xsl:attribute>
+    <xsl:attribute name="margin-left">0.5em</xsl:attribute>
+    <xsl:attribute name="margin-right">0.5em</xsl:attribute>
+    <xsl:attribute name="keep-together.within-page">always</xsl:attribute>
+  </xsl:attribute-set>
 
   <xsl:attribute-set name="note-warning-title">
     <xsl:attribute name="font-size">1.33em</xsl:attribute>
-- 
cgit v1.2.3