-
Replace @1@replaceable@1@...@2@replaceable@2@ with @3@replaceable@3@...@3@replaceable@3@ inside of :samp: and :file: so that all remaining @1@replaceable@1@...@2@replaceable@2@ are outside. Since the {...} syntax for replaceable only works in :samp: and :file:, we will have to enclose the remaining ones in :samp: for them to work. -
:option: is stronger and assumes a reference to a list of options. Since we don't have that yet, just use :samp: for options. Inside literal code blocks, there is no expansion, so just remove markup.
-
Replace @1@...@2@ stuff from prior to the conversion with new representation.
-
Pandoc indented lists with two spaces after the dash, which is ugly and messes up emacs fill-paragraph. I transformed the spacing using a combination of this perl script and manual edits. I verified that the HTML generated by sphinx was identical before and after the edits and that this commit contains only whitespace changes. The perl script as it stands does not do indentation quite right for variable lists, but there were only about 8 cases that it missed, so I just fixed them manually. ```perl #!/usr/bin/env perl require 5.008; use warnings; use strict; use File::Basename; my $whoami = basename($0); my @liststack = (); while (<>) { if (m/^( *- )\S/) { my $pre = $1; while ((scalar(@liststack) > 0) && ($liststack[-1] >= length($pre))) { pop(@liststack); } if ((scalar(@liststack) == 0) && ($pre =~ m/^ /)) { push(@liststack, 1); } push(@liststack, length($pre)); my $n = scalar(@liststack); #print "** $n\n"; my $newpre = (' ' x ($n - 1)) . '- '; s/^$pre/$newpre/; } elsif (scalar(@liststack) > 0) { if ($_ ne "\n") { while (scalar(@liststack) > 0) { my $pre = m/^( *)/; if (length($1) < $liststack[-1]) { #print "XXX pop\n"; pop(@liststack); } else { last; } } my $n = scalar(@liststack); #print "** $n\n"; my $indent = ' ' x $n; s/^ +/$indent/; } } print; } ``` -
These showed up as warnings from sphinx-build
-
Also remove linearization from qpdf-manual.pdf. It's a small file, and removing the dependency on the qpdf executable significantly shortens build times.
-
pandoc -f docbook -t rst qpdf-manual.xml >| /tmp/a.rst Insert /tmp/a.rst into existing index.rst
-
Run sphinx-quickstart. Throw everything away except conf.py and index.rst. We will incorporate this into our own build system.
-
We were using SGML entities for various non-ASCII characters so they could convert properly for both HTML and print, but this is no longer necessary as we move from docbook to RST, so just replace them. Note that the conversions done by sphinx automatically handle "smart quotes", so it works to just use regular quotes in place of &LDQUO; and &RDQUO;.
-
Pandoc docbook -> rst fails to convert the following elements, so change them to @1@tag@1@ ... @2@tag@2@ for later processing. This way, they will survive the conversion, and we can deal with them later. <application> <command> <filename> <firstterm> <option> <replaceable>
-
With docbook, this was not converted properly in the PDF version, but since we are moving out of docbook, we can just put the Unicode character in the source.
-
Footnotes are yucky in online documentation, and the one footnote in the doc is no longer needed, so remove it.
-
Make a list of things that need to be done while converting docbook to sphinx/rst.
-
* Make it a runtime error, not a logic error * Include additional information * Capture it properly in checkLinearization
-
* Handle error conditions that occur when using the object handle interfaces. In the past, some exceptions were not correctly converted to errors or warnings. * Add more detailed information to qpdf-c.h * Make it possible to work more explicitly with uninitialized objects
-
It was exercised in the pdf-linearize example but not in qpdf-ctest.
-
Thanks for the nudge from m-holger!
-
The impact on the code would be extremely high, and using it would clutter the code greatly because it would break chaining like a.getKey("/B").getKey("/C"). There are better ways to deal with the issue.
