Commit e5c2bd8b14341d82b0d07da560298b85db110ef1
1 parent
29384eca
TODO: doc conversion notes
Make a list of things that need to be done while converting docbook to sphinx/rst.
Showing
1 changed file
with
62 additions
and
0 deletions
TODO
| @@ -17,6 +17,68 @@ Next | @@ -17,6 +17,68 @@ Next | ||
| 17 | thrown when an uninitialized trailer is accessed provides useful | 17 | thrown when an uninitialized trailer is accessed provides useful |
| 18 | information. Test from the C API as well as the C++ API. | 18 | information. Test from the C API as well as the C++ API. |
| 19 | 19 | ||
| 20 | +Doc conversion Notes | ||
| 21 | +==================== | ||
| 22 | + | ||
| 23 | +Things to fix: | ||
| 24 | + | ||
| 25 | +Entities/Unicode | ||
| 26 | + | ||
| 27 | +Gajic -> Gajić | ||
| 28 | + | ||
| 29 | +<!ENTITY lastreleased "November 16, 2021"> (not needed) | ||
| 30 | +<!ENTITY ldquo "“"> | ||
| 31 | +<!ENTITY mdash "—"> | ||
| 32 | +<!ENTITY nbsp " "> | ||
| 33 | +<!ENTITY ndash "–"> | ||
| 34 | +<!ENTITY rdquo "”"> | ||
| 35 | +<!ENTITY swversion "10.4.0"> -> |release| | ||
| 36 | + | ||
| 37 | +Elements: | ||
| 38 | + | ||
| 39 | +See https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html | ||
| 40 | + | ||
| 41 | +<appendix>/<chapter>/<preface> -- no distinction | ||
| 42 | +<programlisting> went to :: -- check them each | ||
| 43 | +Make sure the information from <book> is in there | ||
| 44 | +<xref> -- find #ref. in converted rst | ||
| 45 | +Correct placement of comment: <!-- This section is referenced in QPDFObjectHandle.hh --> | ||
| 46 | + | ||
| 47 | +<application>, <command> -> :command: | ||
| 48 | +<filename> -> :file: (allows {x}) | ||
| 49 | +<option> -> :samp: (allows {x}) | ||
| 50 | +<firstterm> -> just use literal | ||
| 51 | +<replaceable> -> Make sure in :file: or :samp:, then use {} | ||
| 52 | + | ||
| 53 | +Build: | ||
| 54 | + | ||
| 55 | +apt install python3-pip texlive-latex-extra latexmk | ||
| 56 | +pip install sphinx | ||
| 57 | + | ||
| 58 | +sphinx-build -M help . . | ||
| 59 | +sphinx-build -M latexpdf source build | ||
| 60 | +sphinx-build -M html source build | ||
| 61 | +sphinx-build -M singlehtml source build | ||
| 62 | + | ||
| 63 | +autoconf should detect sphinx and its dependencies, not fop, etc. | ||
| 64 | +Remove VALIDATE_DOC | ||
| 65 | +Fix installation of documentation in doc | ||
| 66 | + | ||
| 67 | +Additional cleanup: | ||
| 68 | + | ||
| 69 | +* Indices and tables section | ||
| 70 | + | ||
| 71 | +Future work: | ||
| 72 | + | ||
| 73 | +* :ref: -- would be nice if it were suitable for printed documentation | ||
| 74 | +* README-maintainer: Fix installation of documentation to website | ||
| 75 | +* Release notes link changed (need #ref.release-notes as well as #release-note) | ||
| 76 | +* Decide about readthedocs; if using, with multiple versions/latest | ||
| 77 | +* Change order of sections | ||
| 78 | +* Get navigation working properly | ||
| 79 | +* Generate stuff (options, code samples, etc.) as needed | ||
| 80 | +* Figure out where to put :ref:`search` so we get doc search | ||
| 81 | + | ||
| 20 | Documentation | 82 | Documentation |
| 21 | ============= | 83 | ============= |
| 22 | 84 |