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 &apos;backwards-compatible&apos;. 
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 &apos;|&apos; 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 &apos;\\&apos; 
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 (&quot;\-&quot;), underscores 
(&quot;\_&quot;), colons (&quot;:&quot;), and periods (&quot;.&quot;). 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 &apos;a&apos;
+- Any spaces are replaced with an underscore &apos;\_&apos;
+- 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 &apos;_local_&apos; 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 
&apos;\#&apos;.
+
+- 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 &quot;./&quot;.
+
+- 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 
&apos;backwards-compatible&apos;. 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 &apos;|&apos; 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 &apos;\\&apos; 
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 (&quot;\-&quot;), underscores 
(&quot;\_&quot;), colons (&quot;:&quot;), and periods (&quot;.&quot;). 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 &apos;a&apos;
-- Any spaces are replaced with an underscore &apos;\_&apos;
-- 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 &apos;_local_&apos; 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 
&apos;\#&apos;.
-
-- 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 &quot;./&quot;.
-
-- 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"/>

Reply via email to