Skip to content

Commit

Permalink
Add Admonition Boxes
Browse files Browse the repository at this point in the history 
see issue frankluebeck#74
  • Loading branch information
@kiryph
kiryph committed Oct 24, 2024
1 parent 2eb466c commit 9ea8443
Show file tree
Hide file tree
Showing 11 changed files with 499 additions and 14 deletions.
42 changes: 42 additions & 0 deletions doc/refdtd.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1338,6 +1338,48 @@ It may appear in the output.

</Subsection>

<Subsection Label="Admonition"><Heading><C>&lt;Admonition></C></Heading>
<Index Key="Admonition"><C>Admonition</C></Index>

<Listing Type="From gapdoc.dtd">
<![CDATA[<!ELEMENT Admonition (%Text;| Caption)*>
<!ATTLIST Admonition Type CDATA #REQUIRED
Label CDATA #IMPLIED>]]>
</Listing>

Five types of admonition boxes
<Log><![CDATA[
<Admonition Type="Note">
Useful information that users should know, even when skimming content.
</Admonition>
<Admonition Type="Tip">
Helpful advice for doing things better or more easily.
</Admonition>
<Admonition Type="Important">
Key information users need to know to achieve their goal.
</Admonition>
<Admonition Type="Warning">
Urgent info that needs immediate user attention to avoid problems.
</Admonition>
<Admonition Type="Caution">
Advises about risks or negative outcomes of certain actions.
</Admonition>
]]></Log>

It is possible to customize the caption:

<Log><![CDATA[
<Admonition Type="Important">
<Caption>Important: Custom Caption</Caption>
This is important.
</Admonition>
]]></Log>

</Subsection>

<Subsection Label="Log"><Heading><C>&lt;Log></C> and
<C>&lt;Example></C></Heading>
Expand Down
226 changes: 222 additions & 4 deletions example/example.xml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -512,15 +512,120 @@ And some more for mathematical symbols:

</Section>

<Section><Heading>Admonition Boxes</Heading>
<Label Name="ElevenBack"/>

[&see; <Ref Sect="Eleven"/>]<P/>

Five types of admonition boxes:<P/>

<Admonition Type="Note">
Useful information that users should know, even when skimming content.
</Admonition>

<Admonition Type="Tip">
Helpful advice for doing things better or more easily.
</Admonition>

<Admonition Type="Important">
Key information users need to know to achieve their goal.
</Admonition>

<Admonition Type="Warning">
Urgent info that needs immediate user attention to avoid problems.
</Admonition>

<Admonition Type="Caution">
Advises about risks or negative outcomes of certain actions.
</Admonition>

Custom captions:<P/>

<Admonition Type="Important">
<Caption>Important: Custom Caption</Caption>
Key information users need to know to achieve their goal.
</Admonition>

Other <Package>GAPDoc</Package> elements within admonition boxes are allowed:<P/>

<Admonition Type="Note">
<Caption>A note with <C>Log</C></Caption>
An example with syntax highlighting:
<Br/><Ignore> manually fixing space</Ignore>
<Log>
gap&gt; Sieve(100);
[ 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61,
67, 71, 73, 79, 83, 89, 97 ]
gap&gt; Length(last);
25
</Log>
</Admonition>

<Admonition Type="Note">
<Caption>A note with various <Package>GAPDoc</Package> elements</Caption>

A word with quotation marks: <Q>hello</Q>.

Display Math:

<Display>
\Longrightarrow \quad \left(\sum_{i=1}^d x_i b_i \right) \cdot
\left(\sum_{j=1}^d y_j b_j \right) =
\sum_{k=1}^d \left( \sum_{i,j} x_i y_j h_{ijk} \right) b_k
</Display>

Tables can be used within admonition boxes:
<Br/><Ignore> manually fixing space</Ignore>
<Table Align="|l|l|">
<Caption>Predefined Entities in the &GAPDoc; system</Caption>
<HorLine/>
<Row> <Item><C>&amp;GAP;</C></Item> <Item>&GAP;</Item> </Row>
<HorLine/>
<Row> <Item><C>&amp;GAPDoc;</C></Item> <Item>&GAPDoc;</Item> </Row>
<HorLine/>
<Row> <Item><C>&amp;TeX;</C></Item> <Item>&TeX;</Item> </Row>
<HorLine/>
<Row> <Item><C>&amp;LaTeX;</C></Item> <Item>&LaTeX;</Item> </Row>
<HorLine/>
</Table>

Lists or enumerations can be used within admonition boxes
<List>
<Item>
<Emph>This</Emph> is <E>emphasized</E>.
</Item>
<Item>
<E>Keywords</E> are typeset like <Keyword>this</Keyword> and <K>that</K>.
</Item>
</List>

<List>
<Mark>lists:</Mark><Item> not numbered</Item>
<Mark>enumerations:</Mark><Item> numbered</Item>
<Mark>tables:</Mark><Item> two-dimensional</Item>
</List>

<Enum>
<Item>
<Emph>This</Emph> is <E>emphasized</E>.
</Item>
<Item>
<E>Keywords</E> are typeset like <Keyword>this</Keyword> and <K>that</K>.
</Item>
</Enum>
</Admonition>

</Section>

</Chapter>

</Body>

<Appendix Label="Appendix">
<Heading>An Appendix</Heading>
<Label Name="ElevenBack"/>
<Label Name="TwelveBack"/>

[&see; <Ref Sect="Eleven"/>]<P/>
[&see; <Ref Sect="Twelve"/>]<P/>

This is an appendix.
</Appendix>
Expand Down Expand Up @@ -1078,6 +1183,119 @@ And here are the predefined entities in &GAPDoc;:
And some more for mathematical symbols:
&CC;, &ZZ;, &NN;, &PP;, &QQ;, &HH;, &RR;.
</Section>]]>
</Listing>

</Section>

<Section Label="Eleven"><Heading>Admonition Boxes (Source)</Heading>

[<Ref Label="ElevenBack"/>]

<Listing>
<![CDATA[<Section><Heading>Admonition Boxes</Heading>
<Label Name="ElevenBack"/>
[&see; <Ref Sect="Eleven"/>]<P/>
Five types of admonition boxes:<P/>
<Admonition Type="Note">
Useful information that users should know, even when skimming content.
</Admonition>
<Admonition Type="Tip">
Helpful advice for doing things better or more easily.
</Admonition>
<Admonition Type="Important">
Key information users need to know to achieve their goal.
</Admonition>
<Admonition Type="Warning">
Urgent info that needs immediate user attention to avoid problems.
</Admonition>
<Admonition Type="Caution">
Advises about risks or negative outcomes of certain actions.
</Admonition>
Custom captions:<P/>
<Admonition Type="Important">
<Caption>Important: Custom Caption</Caption>
Key information users need to know to achieve their goal.
</Admonition>
Other <Package>GAPDoc</Package> elements within admonition boxes are allowed:<P/>
<Admonition Type="Note">
<Caption>A note with <C>Log</C></Caption>
An example with syntax highlighting:
<Br/><Ignore> manually fixing space</Ignore>
<Log>
gap&gt; Sieve(100);
[ 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61,
67, 71, 73, 79, 83, 89, 97 ]
gap&gt; Length(last);
25
</Log>
</Admonition>
<Admonition Type="Note">
<Caption>A note with various <Package>GAPDoc</Package> elements</Caption>
A word with quotation marks: <Q>hello</Q>.
Display Math:
<Display>
\Longrightarrow \quad \left(\sum_{i=1}^d x_i b_i \right) \cdot
\left(\sum_{j=1}^d y_j b_j \right) =
\sum_{k=1}^d \left( \sum_{i,j} x_i y_j h_{ijk} \right) b_k
</Display>
Tables can be used within admonition boxes:
<Br/><Ignore> manually fixing space</Ignore>
<Table Align="|l|l|">
<Caption>Predefined Entities in the &GAPDoc; system</Caption>
<HorLine/>
<Row> <Item><C>&amp;GAP;</C></Item> <Item>&GAP;</Item> </Row>
<HorLine/>
<Row> <Item><C>&amp;GAPDoc;</C></Item> <Item>&GAPDoc;</Item> </Row>
<HorLine/>
<Row> <Item><C>&amp;TeX;</C></Item> <Item>&TeX;</Item> </Row>
<HorLine/>
<Row> <Item><C>&amp;LaTeX;</C></Item> <Item>&LaTeX;</Item> </Row>
<HorLine/>
</Table>
Lists or enumerations can be used within admonition boxes
<List>
<Item>
<Emph>This</Emph> is <E>emphasized</E>.
</Item>
<Item>
<E>Keywords</E> are typeset like <Keyword>this</Keyword> and <K>that</K>.
</Item>
</List>
<List>
<Mark>lists:</Mark><Item> not numbered</Item>
<Mark>enumerations:</Mark><Item> numbered</Item>
<Mark>tables:</Mark><Item> two-dimensional</Item>
</List>
<Enum>
<Item>
<Emph>This</Emph> is <E>emphasized</E>.
</Item>
<Item>
<E>Keywords</E> are typeset like <Keyword>this</Keyword> and <K>that</K>.
</Item>
</Enum>
</Admonition>
</Section>
</Chapter>
Expand All @@ -1088,9 +1306,9 @@ And some more for mathematical symbols:
</Section>


<Section Label="Eleven"><Heading>Appendix (Source)</Heading>
<Section Label="Twelve"><Heading>Appendix (Source)</Heading>

[<Ref Label="ElevenBack"/>]
[<Ref Label="TwelveBack"/>]

<Listing Type="GAPDoc source">
<![CDATA[<Appendix><Heading>An Appendix</Heading>
Expand Down
9 changes: 8 additions & 1 deletion gapdoc.dtd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@
environments like enumerations, lists, and such.
================================================================== -->

<!ENTITY % Text "%InnerText; | List | Enum | Table">
<!ENTITY % Text "%InnerText; | List | Enum | Table | Admonition">

<!ELEMENT Item ( %Text;)*>
<!ELEMENT Mark ( %InnerText;)*>
Expand All @@ -265,6 +265,13 @@
<!ELEMENT HorLine EMPTY>
<!ELEMENT Caption ( %InnerText;)*>

<!ELEMENT Admonition (%Text;| Caption)*>
<!--<!ATTLIST Admonition Type (Note|Tip|Important|Warning|Caution|Quote) #REQUIRED
GAP/GAPDoc does not have a proper dtd parser which understands "enumerated attribute values"
-->
<!ATTLIST Admonition Type CDATA #REQUIRED
Label CDATA #IMPLIED> <!-- For reference purposes -->

<!-- ==================================================================
We start defining some things within the overall structure:
================================================================== -->
Expand Down
1 change: 1 addition & 0 deletions lib/GAPDoc.gi
View file
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,7 @@ InstallGlobalFunction(CheckAndCleanGapDocTree, function(arg)
= "XML") or c.name in
GAPDOCDTDINFO[pos].content);
if false in l then
Print(GAPDOCDTDINFO[pos].content);
ParseError(str, r.start, Concatenation("Wrong element in ",
name, ": ", r.content[Position(l, false)].name));
fi;
Expand Down
33 changes: 32 additions & 1 deletion lib/GAPDoc2HTML.gi
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ GAPDoc2HTMLProcs.TextAttr.GAPinput :=

# like in Text converter, but a heading and an address are not a paragraph here
GAPDoc2HTMLProcs.ParEls :=
[ "Display", "Example", "Log", "Listing", "List", "Enum", "Item", "Table",
[ "Display", "Example", "Log", "Listing", "List", "Enum", "Item", "Table", "Admonition",
"TitlePage", "Abstract", "Copyright", "Acknowledgements",
"Colophon", "TableOfContents", "Bibliography", "TheIndex",
"Subsection", "ManSection", "Description", "Returns", "Section",
Expand Down Expand Up @@ -2124,6 +2124,37 @@ GAPDoc2HTMLProcs.Row := function(r, str, al)
Append(str, "</tr>\n");
end;

GAPDoc2HTMLProcs.Admonition := function(r, par)
local str, cap, tmp, pars, i;

str := "\n<aside class=\"admonition ";
Append(str, LowercaseString(r.attributes.Type));
Append(str, "\">");

# Title
Append(str, "\n<p class=\"admonition-title\">");
# Optional custom title
cap := Filtered(r.content, a-> a.name = "Caption");
if Length(cap) > 0 then
tmp := "";
GAPDoc2HTMLContent(cap[1], tmp);
Append(str, tmp);
else
Append(str, r.attributes.Type);
fi;
Append(str, "</p>\n");

pars := "";
GAPDoc2HTMLContent(r, pars);
for i in [1..Length(pars)/2] do
Append(str, pars[i*2]);
od;

Append(str, "</aside>\n\n");

Add(par, r.count);
Add(par, str);
end;

##
## <#GAPDoc Label="GAPDoc2HTMLPrintHTMLFiles">
Expand Down
Loading

0 comments on commit 9ea8443

Please sign in to comment.