[MNGSITE-507] Convert APT to Markdown

[kwin]

The converter from
apache/maven-doxia-converter@4061da5 was used with the following options:

java -jar doxia-converter-1.4-SNAPSHOT-shaded.jar -in ./content/apt -from apt -out ./content/markdown -to markdown -removeIn

[kwin]

After applying tons of fixes to Doxia and Converter this looks good to me now.

[michael-o]

Did you diff the produced HTML? Especially <section> elements are missing and CSS isn't properly applied.

[kwin]

I don't care about the HTML differences too much, I manually validated that the content looks reasonable now. I haven't found any obvious issue with CSS.

[michael-o]

I don't care about the HTML differences too much, I manually validated that the content looks reasonable now. I haven't found any obvious issue with CSS.

One of the problems I have seen multiple times: https://github.com/apache/maven-fluido-skin/blob/master/src/main/resources/css/maven-base.css

[kwin]

@michael-o Can you be more specific? I fail to see the relation between this conversion and a general CSS resource of the fluido-skin. What exactly is incorrectly rendered?

[michael-o]

The first difference I see is that comments are fully retained. The generated HTML contains the license header. Waste, isn't it? The comments which aren't HTML style should be stripped.

Is this the bug: https://github.com/apache/maven-doxia/blob/e6190a9aa5121bfda9bb4efac3acd4cbbfee5880/doxia-modules/doxia-module-markdown/src/main/java/org/apache/maven/doxia/module/markdown/MarkdownParser.java#L291-L306?

[michael-o]

Next diff: Code blocks from APT, not verbatim ones are lost, so is autohighlight. Example: developers/committer-settings.html

[michael-o]

conventions/code.html misses anchors as well es in other files. Explicit anchors are lost.

[kwin]

Next diff: Code blocks from APT, not verbatim ones are lost, so is autohighlight. Example: developers/committer-settings.html

Well, https://maven.apache.org/developers/committer-settings.html has the following APT:

maven-site/content/apt/developers/committer-settings.apt

Lines 41 to 60 in 923f866

	+-----+
	<settings>
	...
	<servers>
	<!-- To publish a snapshot of some part of Maven -->
	<server>
	<id>apache.snapshots.https</id>
	<username> <!-- YOUR APACHE LDAP USERNAME --> </username>
	<password> <!-- YOUR APACHE LDAP PASSWORD --> </password>
	</server>
	<!-- To stage a release of some part of Maven -->
	<server>
	<id>apache.releases.https</id>
	<username> <!-- YOUR APACHE LDAP USERNAME --> </username>
	<password> <!-- YOUR APACHE LDAP PASSWORD --> </password>
	</server>
	...
	</servers>
	</settings>
	+-----+

According to https://maven.apache.org/doxia/references/apt-format.html#verbatim-text this is just verbatim text with a box around it.
This is converted to https://github.com/apache/maven-site/pull/573/files#diff-ad6899066ecffca374fb2b9eb533e56c42e397026a9a577f78c42ac3fae9902cR36.

I see that the HTML generated out of the converted MD is lacking the hightlighting and line number, but I think this is due to https://issues.apache.org/jira/browse/MSKINS-245 because the HTML looks good to me i.e. enclosed in {{

...

}}. In MD every verbatim text is emitted in code blocks!

What exactly do you consider wrong here @michael-o ?

[kwin]

The first difference I see is that comments are fully retained.

This is not new and not strictly related to the conversion but I tracked this now in https://issues.apache.org/jira/browse/DOXIA-758

[kwin]

conventions/code.html misses anchors as well es in other files. Explicit anchors are lost.

Tracked in https://issues.apache.org/jira/browse/DOXIA-759