This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new b3ccaccd Combine the APT format and the Doxia APT enhancements in one
page
b3ccaccd is described below
commit b3ccaccd1283204b6d46c7fb5ae4a86f47970196
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Wed Nov 4 12:43:58 2026 +0000
Combine the APT format and the Doxia APT enhancements in one page
MNGSITE-403. The old doxia-apt.html redirects to apt-format.html; the
enhancement sections keep their anchor ids, and browsers carry the #fragment
across the redirect.
---
content/markdown/doxia/macros/index.md | 2 +-
content/markdown/doxia/references/apt-format.md | 162 ++++++++++++++++++++-
content/markdown/doxia/references/doxia-apt.md | 180 ------------------------
content/resources/doxia/.htaccess | 3 +
content/site.xml | 2 +-
5 files changed, 163 insertions(+), 186 deletions(-)
diff --git a/content/markdown/doxia/macros/index.md
b/content/markdown/doxia/macros/index.md
index be8b3f70..5a8ee826 100644
--- a/content/markdown/doxia/macros/index.md
+++ b/content/markdown/doxia/macros/index.md
@@ -149,7 +149,7 @@ The _TOC_ macro prints a Table Of Content of a document. It
is useful if you hav
This displays a TOC for the second section in the document, including all
subsections (depth 2) and sub-subsections (depth 3).
-**Note** that when a site is rendered, Doxia anchors each section title for
you, so the entries this macro emits resolve without further work. Define an
anchor explicitly (see [Enhancements to the APT
format](../references/doxia-apt.html)) where a link has to survive the title
being reworded.
+**Note** that when a site is rendered, Doxia anchors each section title for
you, so the entries this macro emits resolve without further work. Define an
anchor explicitly (see [Enhancements to the APT
format](../references/apt-format.html#Enhancements_to_the_APT_format)) where a
link has to survive the title being reworded.
In a xdoc file, it will be:
diff --git a/content/markdown/doxia/references/apt-format.md
b/content/markdown/doxia/references/apt-format.md
index 00b0e480..735ce84c 100644
--- a/content/markdown/doxia/references/apt-format.md
+++ b/content/markdown/doxia/references/apt-format.md
@@ -2,6 +2,8 @@
title: The APT format
author:
- Jason van Zyl
+ - Lukas Theussl
+ - Robert Scholte
date: 2009-03-02
---
@@ -34,7 +36,7 @@ This document provides some examples of available APT
formatting.
## Important Notice
-The information contained in this document corresponds to the original APT
format as published by [Xmlmind](http://www.xmlmind.com/). In version 1\.1
Maven Doxia has applied several modifications to this original format, see this
separate [document](./doxia-apt.html) for a detailed description. Notable
differences are highlighted below with a [\[Change\]](./doxia-apt.html) link.
+The information contained in this document corresponds to the original APT
format as published by [Xmlmind](http://www.xmlmind.com/). In version 1\.1
Maven Doxia has applied several modifications to this original format,
described in [Enhancements to the APT format](#Enhancements_to_the_APT_format)
at the end of this document. Notable differences are highlighted below with a
[\[Change\]](#Enhancements_to_the_APT_format) link.
The following sections contain formatted text that demonstrates the use of APT
to create paragraphs, headers, sections, lists, code samples, figures, tables,
rules, breaks, and text level elements such as font styles, anchors, and
special characters. Boxes containing text in typewriter-like font are examples
of APT source.
@@ -295,7 +297,7 @@ Like in HTML, verbatim text is preformatted. Unlike HTML,
verbatim text is escap
A figure block is not indented. It begins with the figure name between square
brackets. The figure name is optionally followed by some text: the figure
caption.
-The figure name is the pathname of the file containing the figure but without
an extension. Example: if your figure is contained in
`/home/joe/docs/mylogo.jpeg`, the figure name is `/home/joe/docs/mylogo`.
[\[Change\]](./doxia-apt.html#Figure_extensions)
+The figure name is the pathname of the file containing the figure but without
an extension. Example: if your figure is contained in
`/home/joe/docs/mylogo.jpeg`, the figure name is `/home/joe/docs/mylogo`.
[\[Change\]](#Figure_extensions)
If the figure name comes from a relative pathname (recommended practice)
rather than from an absolute pathname, this relative pathname is taken to be
relative to the directory of the current APT document (a la HTML) rather than
relative to the current working directory.
@@ -390,7 +392,7 @@ It is not recommended to use font elements inside titles,
section titles, links
Text between curly braces (`{}`) specifies an anchor. Text between double
curly braces (`{{}}`) specifies a link.
-It is an error to create a link element that does not refer to an anchor of
the same name. The name of an anchor/link is its text with all non alphanumeric
characters stripped. [\[Change\]](./doxia-apt.html#Anchor_construction)
+It is an error to create a link element that does not refer to an anchor of
the same name. The name of an anchor/link is its text with all non alphanumeric
characters stripped. [\[Change\]](#Anchor_construction)
This rule does not apply to links to _external_ anchors. Text beginning with
`http:/`, `https:/`, `ftp:/`, `file:/`, `mailto:`, `../`, `./` (`..\` and `.\`
on Windows) is recognized as an external anchor name.
@@ -398,7 +400,7 @@ When the construct **\{\{\{**_name_**\}**_text_**\}\}** is
used, the link text _
Anchor/link elements may appear anywhere except inside other anchor/link
elements.
-Section titles are implicitly defined anchors.
[\[Change\]](./doxia-apt.html#Anchors_for_section_titles)
+Section titles are implicitly defined anchors.
[\[Change\]](#Anchors_for_section_titles)
#### Line break
@@ -564,3 +566,155 @@ Table caption
~~Commented out.
```
+## Enhancements to the APT format
+
+<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+
+In the following we provide a list of differences/enhancements to the original
APT format described above that were incorporated in Doxia. Apart from some
exceptions, these differences are usually 'backwards-compatible'.
That is, any document that gets correctly processed by Aptconvert should also
be a valid Doxia input file and lead to identical results when processed by a
Doxia parser.
+
+### <a id="Paragraphs_in_list_items"></a>Paragraphs in list items
+
+<!--~~~~~~~~~~~~~~~~~~~~~~~~~~-->
+
+Contrary to the original APT parser, the Doxia APT parser does not put list
items within paragraphs. Eg, the example given in the APT guide:
+
+```text
+ * List item 1.
+```
+
+will, for instance, produce the following html:
+
+```xml
+ <li>List item 1.</li>
+```
+
+To get the same result as aptconvert, use
+
+```text
+ *
+
+ List item 1.
+```
+
+which will produce:
+
+```xml
+ <li><p>List item 1.</p></li>
+```
+
+### <a id="Table_header_cells"></a>Table header cells
+
+<!--~~~~~~~~~~~~~~~~~~~~-->
+
+Header cells are defined by an additional pipe character '|' at the
beginning of the cell:
+
+```text
+*-----------+-----------+
+|| Header 1 || Header 2 |
+*-----------+-----------+
+| Cell 1 | Cell 2 |
+*-----------+-----------+
+```
+
+produces:
+
+|Header 1|Header 2|
+|:---|:---|
+|Cell 1|Cell 2|
+### <a id="Multi-lines_cells_in_table"></a>Multi-lines cells in table
+
+<!--~~~~~~~~~~~~~~~~~~~~-->
+
+Since 1\.1, multi-lines cells are recognized with the character '\\'
at the end of the cells:
+
+```text
+*-----------+-----------+
+|| Header 1 || Header 2 |
+*-----------+-----------+
+| Cell\ | Cell 2 |
+| 1 | |
+*-----------+-----------+
+```
+
+produces:
+
+|Header 1|Header 2|
+|:---|:---|
+|Cell<br />1|Cell 2|
+### <a id="Anchors"></a>Anchors
+
+<!--~~~~~~~~~~~~~~~~~~~-->
+#### <a id="Anchors_for_section_titles"></a>Anchors for section titles
+
+When a document is rendered as part of a Maven site, Doxia gives every section
title an anchor of its own, built from the title text by the rules below.
Because that name follows the wording, rewording a title moves the anchor and
breaks links aimed at it. Define the anchor explicitly where a reference has to
hold:
+
+```text
+* {Anchors for section titles}
+```
+
+#### <a id="Anchor_construction"></a>Anchor construction
+
+Contrary to the original APT format, an anchor/link is **not** its text with
all non alphanumeric characters stripped. Ideally, an anchor should be a valid
Doxia id, ie it must begin with a letter (\[A-Za-z\]) and may be followed by
any number of letters, digits (\[0-9\]), hyphens ("\-"), underscores
("\_"), colons (":"), and periods ("."). Any
anchor that does not satisfy this pattern is transformed according to the
following rules:
+
+- Any whitespace at the start and end is removed
+- If the first character is not a letter, prepend the letter 'a'
+- Any spaces are replaced with an underscore '\_'
+- Any characters not matching the above pattern are stripped.
+
+Note in particular that case is preserved in this conversation and that APT
anchors and links are case-sensitive. So the anchor for the section title in
the previous example would be `Anchors_for_section_titles`.
+
+### <a id="Links"></a>Links
+
+<!--~~~~~~~~~~~~~~~~~~~-->
+
+In **Doxia-1\.1** the notion of a '_local_' link was introduced in
addition to _internal_ links and _external_ links.
+
+- An **internal** link is a link to an anchor within the same source document.
+
+ In the APT format used by **Doxia-1\.1**, internal links have to be valid
Doxia ids, as specified in the anchors section above.
+
+ Note in particular that internal links in APT do **not** start with
'\#'.
+
+- A **local** link is a link to another document within the same site.
+
+ In the APT format used by **Doxia-1\.1**, local links **have to** start
with either `./` or `../` to distinguish them from internal links. E.g.,
+
+ ```
+ {{{doc/standalone.html}Standalone}}
+ ```
+
+ is not valid, it should be
+
+ ```
+ {{{./doc/standalone.html}Standalone}}
+ ```
+
+ Note in particular that the following link
+
+ ```
+ {{{standalone.html}Standalone}}
+ ```
+
+ will be interpreted as an internal link (dots are valid characters in
anchor names). Since you most likely meant to link to another source document,
you should again prepend a "./".
+
+- An **external** link is a link that is neither local nor internal.
+
+ An external link should be a valid
[URI](http://www.ietf.org/rfc/rfc2396.txt).
+
+Anchors are always translated to a valid id, including escaping. In some
situation this can cause issues, especially when referring to a javadoc-link.
+Since Doxia 1\.4 there is support for literal anchors, by using 2 hashed
(\#\#) instead of 1\. This implies that the writer is responsible for using the
right URL encoding!
+
+```
+
{{{../apidocs/groovyx/net/http/ParserRegistry.html##parseText(org.apache.http.HttpResponse)}ParserRegistry}}
+```
+
+### <a id="Figure_extensions"></a>Figure extensions
+
+<!--~~~~~~~~~~~~~~~~~~~-->
+
+Contrary to the original APT format, a figure name has to be given fully
**with** extension. For instance:
+
+```text
+[/home/joe/docs/mylogo.jpeg] Figure caption
+```
+
diff --git a/content/markdown/doxia/references/doxia-apt.md
b/content/markdown/doxia/references/doxia-apt.md
deleted file mode 100644
index 50a59d99..00000000
--- a/content/markdown/doxia/references/doxia-apt.md
+++ /dev/null
@@ -1,180 +0,0 @@
----
-title: Doxia APT Enhancements
-author:
- - Lukas Theussl
- - Robert Scholte
-date: 2013-04-06
----
-
-<!--
-Licensed to the Apache Software Foundation (ASF) under one
-or more contributor license agreements. See the NOTICE file
-distributed with this work for additional information
-regarding copyright ownership. The ASF licenses this file
-to you under the Apache License, Version 2.0 (the
-"License"); you may not use this file except in compliance
-with the License. You may obtain a copy of the License at
-
-http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing,
-software distributed under the License is distributed on an
-"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-KIND, either express or implied. See the License for the
-specific language governing permissions and limitations
-under the License.
--->
-
-# Enhancements to the APT format
-
-<!--~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-
-In the following we provide a list of differences/enhancements to the original
[APT](./apt-format.html) format that were incorporated in Doxia. Apart from
some exceptions, these differences are usually
'backwards-compatible'. That is, any document that gets correctly
processed by Aptconvert should also be a valid Doxia input file and lead to
identical results when processed by a Doxia parser.
-
-<!-- MACRO{toc|section=1|fromDepth=2|toDepth=2} -->
-## <a id="Paragraphs_in_list_items"></a>Paragraphs in list items
-
-<!--~~~~~~~~~~~~~~~~~~~~~~~~~~-->
-
-Contrary to the original APT parser, the Doxia APT parser does not put list
items within paragraphs. Eg, the example given in the APT guide:
-
-```text
- * List item 1.
-```
-
-will, for instance, produce the following html:
-
-```xml
- <li>List item 1.</li>
-```
-
-To get the same result as aptconvert, use
-
-```text
- *
-
- List item 1.
-```
-
-which will produce:
-
-```xml
- <li><p>List item 1.</p></li>
-```
-
-## <a id="Table_header_cells"></a>Table header cells
-
-<!--~~~~~~~~~~~~~~~~~~~~-->
-
-Header cells are defined by an additional pipe character '|' at the
beginning of the cell:
-
-```text
-*-----------+-----------+
-|| Header 1 || Header 2 |
-*-----------+-----------+
-| Cell 1 | Cell 2 |
-*-----------+-----------+
-```
-
-produces:
-
-|Header 1|Header 2|
-|:---|:---|
-|Cell 1|Cell 2|
-## <a id="Multi-lines_cells_in_table"></a>Multi-lines cells in table
-
-<!--~~~~~~~~~~~~~~~~~~~~-->
-
-Since 1\.1, multi-lines cells are recognized with the character '\\'
at the end of the cells:
-
-```text
-*-----------+-----------+
-|| Header 1 || Header 2 |
-*-----------+-----------+
-| Cell\ | Cell 2 |
-| 1 | |
-*-----------+-----------+
-```
-
-produces:
-
-|Header 1|Header 2|
-|:---|:---|
-|Cell<br />1|Cell 2|
-## <a id="Anchors"></a>Anchors
-
-<!--~~~~~~~~~~~~~~~~~~~-->
-### <a id="Anchors_for_section_titles"></a>Anchors for section titles
-
-When a document is rendered as part of a Maven site, Doxia gives every section
title an anchor of its own, built from the title text by the rules below.
Because that name follows the wording, rewording a title moves the anchor and
breaks links aimed at it. Define the anchor explicitly where a reference has to
hold:
-
-```text
-* {Anchors for section titles}
-```
-
-### <a id="Anchor_construction"></a>Anchor construction
-
-Contrary to the original APT format, an anchor/link is **not** its text with
all non alphanumeric characters stripped. Ideally, an anchor should be a valid
Doxia id, ie it must begin with a letter (\[A-Za-z\]) and may be followed by
any number of letters, digits (\[0-9\]), hyphens ("\-"), underscores
("\_"), colons (":"), and periods ("."). Any
anchor that does not satisfy this pattern is transformed according to the
following rules:
-
-- Any whitespace at the start and end is removed
-- If the first character is not a letter, prepend the letter 'a'
-- Any spaces are replaced with an underscore '\_'
-- Any characters not matching the above pattern are stripped.
-
-Note in particular that case is preserved in this conversation and that APT
anchors and links are case-sensitive. So the anchor for the section title in
the previous example would be `Anchors_for_section_titles`.
-
-## <a id="Links"></a>Links
-
-<!--~~~~~~~~~~~~~~~~~~~-->
-
-In **Doxia-1\.1** the notion of a '_local_' link was introduced in
addition to _internal_ links and _external_ links.
-
-- An **internal** link is a link to an anchor within the same source document.
-
- In the APT format used by **Doxia-1\.1**, internal links have to be valid
Doxia ids, as specified in the anchors section above.
-
- Note in particular that internal links in APT do **not** start with
'\#'.
-
-- A **local** link is a link to another document within the same site.
-
- In the APT format used by **Doxia-1\.1**, local links **have to** start
with either `./` or `../` to distinguish them from internal links. E.g.,
-
- ```
- {{{doc/standalone.html}Standalone}}
- ```
-
- is not valid, it should be
-
- ```
- {{{./doc/standalone.html}Standalone}}
- ```
-
- Note in particular that the following link
-
- ```
- {{{standalone.html}Standalone}}
- ```
-
- will be interpreted as an internal link (dots are valid characters in
anchor names). Since you most likely meant to link to another source document,
you should again prepend a "./".
-
-- An **external** link is a link that is neither local nor internal.
-
- An external link should be a valid
[URI](http://www.ietf.org/rfc/rfc2396.txt).
-
-Anchors are always translated to a valid id, including escaping. In some
situation this can cause issues, especially when referring to a javadoc-link.
-Since Doxia 1\.4 there is support for literal anchors, by using 2 hashed
(\#\#) instead of 1\. This implies that the writer is responsible for using the
right URL encoding!
-
-```
-
{{{../apidocs/groovyx/net/http/ParserRegistry.html##parseText(org.apache.http.HttpResponse)}ParserRegistry}}
-```
-
-## <a id="Figure_extensions"></a>Figure extensions
-
-<!--~~~~~~~~~~~~~~~~~~~-->
-
-Contrary to the original APT format, a figure name has to be given fully
**with** extension. For instance:
-
-```text
-[/home/joe/docs/mylogo.jpeg] Figure caption
-```
-
diff --git a/content/resources/doxia/.htaccess
b/content/resources/doxia/.htaccess
index 64f1b0ab..8d699228 100644
--- a/content/resources/doxia/.htaccess
+++ b/content/resources/doxia/.htaccess
@@ -17,3 +17,6 @@ Redirect Permanent /doxia/mailing-lists.html
/mailing-lists.html
Redirect Permanent /doxia/ci-management.html /ci-management.html
Redirect Permanent /doxia/issue-management.html /issue-management.html
Redirect Permanent /doxia/project-info.html /doxia/index.html
+
+# the Doxia APT enhancements were merged into the APT format page; browsers
keep the #fragment
+Redirect Permanent /doxia/references/doxia-apt.html
/doxia/references/apt-format.html
diff --git a/content/site.xml b/content/site.xml
index 2f7c33dd..b7a0b356 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -63,7 +63,7 @@ under the License.
<item name="Format References" href="/doxia/references/index.html"
collapse="true">
<item name="Markdown Format"
href="/doxia/references/markdown-format.html"/>
<item name="Apt Format" href="/doxia/references/apt-format.html"
collapse="true">
- <item name="Doxia Apt Enhancements"
href="/doxia/references/doxia-apt.html"/>
+ <item name="Doxia Apt Enhancements"
href="/doxia/references/apt-format.html#Enhancements_to_the_APT_format"/>
</item>
<item name="FML Format" href="/doxia/references/fml-format.html"/>
<item name="Xdoc Format" href="/doxia/references/xdoc-format.html"/>