<pre style='margin:0'>
Rainer Müller (raimue) pushed a commit to branch master
in repository macports-guide.
</pre>
<p><a href="https://github.com/macports/macports-guide/commit/ff272ed1ffa44a4a89acd4687d8f54cba88a3050">https://github.com/macports/macports-guide/commit/ff272ed1ffa44a4a89acd4687d8f54cba88a3050</a></p>
<pre style="white-space: pre; background: #F8F8F8"><span style='display:block; white-space:pre;color:#808000;'>commit ff272ed1ffa44a4a89acd4687d8f54cba88a3050
</span>Author: Rainer Müller <raimue@macports.org>
AuthorDate: Wed Apr 25 03:16:03 2018 +0200
<span style='display:block; white-space:pre;color:#404040;'> adoc/README: Add list of TODOs for conversion
</span>---
guide/adoc/README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 70 insertions(+)
<span style='display:block; white-space:pre;color:#808080;'>diff --git a/guide/adoc/README.md b/guide/adoc/README.md
</span><span style='display:block; white-space:pre;color:#808080;'>index d1eeacf..ae7ca0d 100644
</span><span style='display:block; white-space:pre;background:#e0e0ff;'>--- a/guide/adoc/README.md
</span><span style='display:block; white-space:pre;background:#e0e0ff;'>+++ b/guide/adoc/README.md
</span><span style='display:block; white-space:pre;background:#e0e0e0;'>@@ -45,3 +45,73 @@ During the initial conversion the following warnings are thrown:
</span> No visitor defined for <glossdiv>! Skipping.
Quite some parts of the guide are not interpreted correctly and might end up being displayed as code rather than actual portion of text.
<span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+## TODO
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+### Incorrectly converted
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+List of things that are incorrectly converted by docbookrx. These should be
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+fixed in docbookrx as they either lose information or affect a lot of
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+locations in the sources.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+* Internal references have an underscore preprended
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ This would break all links to the guide. As docbookrx does not take
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ configuration parameters, this has to be changed in the visitor directly.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+* `<link xlink:href="...">`
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ This is not converted correctly. All external links are broken.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+* Missing distinction between `<programlisting><prompt></><userinput></></>`, `<screen>`, and `<programlisting>`
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ They all result in similar [source] blocks at the moment. Based on how they
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ are used in the guide, we should keep the semantics by adding style
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ attributes to AsciiDoc.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ [cmd]
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ ----
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ $ Commands to be typed into a terminal window.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ ----
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ [output]
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ ----
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ Command output to a terminal window.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ ----
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ [source]
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ ----
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ File text.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ ----
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+* `<option>foo</option>` produces `[option]``foo`` `
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ This also applies to `<replaceable>`, `<path>`, or `<var>` among others.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ It seems overly verbose and unnecessary in most places.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ Backticks alone should be enough, unless we want to apply a specific style to
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ any of these.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+### Postprocessing
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+List of things that need to be fixed manually after running the conversion
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+with docbookrx:
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+* Fix book title
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ Suppress rendering of "MacPorts" in "MacPorts Guide".
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+* Fix authors
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ Or just remove them, as this list is not exhaustive anyway.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+* Fix nested tables in project.adoc
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ docbookrx does not convert nested tables correctly (look for <tbody>).
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ However, nested tables are in fact supported by AsciiDoc, so this can be
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ rescued with manual work.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+* Rewrite internals-hier.adoc
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ None of the original hierarchy could be converted. Rewrite this section
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ in AsciiDoc (and maybe also merge it with porthier.7 in base?).
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+* Rewrite glossary manually or remove it
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ docbookrx does not know about `<glossdiv>`. The glossary only contains
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ two entries, so the usefulness in its current form is doubtful.
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+* Fix leveloffsets in portfileref.adoc
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ Sometimes our includes start a new section and sometimes they contain
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ content for the same level. There is no way for docbookrx to guess
</span><span style='display:block; white-space:pre;background:#e0ffe0;'>+ that correctly, so it needs to be fixed manually.
</span></pre><pre style='margin:0'>
</pre>