<div dir="ltr"><div>We discussed Sean's needs at length on IRC earlier today, and I wanted him to get more input from this list. </div><div><br></div><div>One vision I had early on is "author in any format, we'll make it what we need under the covers through automation." I hate to have writers distracted by tooling if it prevents them from writing what's fresh in their minds. This limitation especially affects Python developer's content. However, we never have discovered a way to have mixed-source in a single collection, and the output from light markup has issues.</div>
<div><br></div>For other books we do the pandoc and cleanup on Jenkins itself. Here's a spelled-out example, which is abstracted with scripts in the openstack-ci projects. <div>For example:</div><div>
<p>
</p><p class="">pandoc -f markdown -t docbook -s <a href="http://image-api-v2.0.md">image-api-v2.0.md</a> | xsltproc -o - /home/stacker/repos/openstack-manuals/doc/src/docbkx/openstack-ha/db4-upgrade.xsl - | xmllint --format - | sed -e "s,<article,<chapter xml:id=\"image-api-v2.0\"," | sed -e 's,</article>,</chapter>,' > image-api-v2.0.xml</p>
<div>We have discovered some issues with the output from these types of non-XML starting points. </div><div><span style="font-family:arial,sans-serif;font-size:13px">- In PDF, title doesn't wrap correctly</span><br style="font-family:arial,sans-serif;font-size:13px">
<span style="font-family:arial,sans-serif;font-size:13px">- Code samples could be resized (smaller) to fit on a page nicely if it were XML</span><br style="font-family:arial,sans-serif;font-size:13px"><span style="font-family:arial,sans-serif;font-size:13px">- Some strange page breaks (which can be better controlled with processing instructions)</span><br style="font-family:arial,sans-serif;font-size:13px">
<span style="font-family:arial,sans-serif;font-size:13px">- chunking can be more finely indicated for the HTML output especially</span><br></div><div><br></div><div>I think for your purposes you would resist a Jenkins-job-based approach because you want to organize the content yourself, is that right? I'd like to push as much of this as possible to Jenkins rather than taking on content in the repo itself. Sounds like David has ideas and Andreas is also quite good at automation. </div>
<div><br></div><div>I do have Todd Morey working on a proof of concept where rather than outputting webhelp we output XHTML and put together collections that could potentially be mixed-content. Ideally we can move to this after the release goes out. I've blocked Sean's patch at <a href="https://review.openstack.org/#/c/50509/">https://review.openstack.org/#/c/50509/</a> until we can revisit after release. </div>
<div><br></div><div>I'm also not quite convinced that a collection of disparate topics is a great way to train Python devs. Your patch doesn't have a book we can look at and build, and I'd like to see that as part of the review considerations for the whole picture here. </div>
<div><br></div><div>Thanks for bringing it to the list -</div>
<div><br></div><div>Anne</div></div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Oct 9, 2013 at 7:00 PM, David Cramer <span dir="ltr"><<a href="mailto:david.cramer@rackspace.com" target="_blank">david.cramer@rackspace.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Hi Sean,<br>
xslt would be well-suited to cleaning up the output of pandoc and<br>
converting it to DocBook 5.x. This could be invoked from your python script:<br>
<br>
<a href="https://svn.code.sf.net/p/docbook/code/trunk/docbook/relaxng/tools/db4-upgrade.xsl" target="_blank">https://svn.code.sf.net/p/docbook/code/trunk/docbook/relaxng/tools/db4-upgrade.xsl</a><br>
<br>
If you have other cleanup to perform, we could add the necessary logic<br>
to the db4-upgrade.xsl.<br>
<br>
I'll be happy to help with the xslt and I think the result would be more<br>
robust.<br>
<br>
Regards,<br>
David<br>
<div><div class="h5"><br>
On 10/09/2013 06:37 PM, Sean Roberts wrote:<br>
> The training-manuals team is proposing a blueprint to implement rst to<br>
> xml conversion script. This code is used to convert devref project rst<br>
> documentation into xml that the openstack manuals project can use. The<br>
> Training-manuals sub-project will use xi:include statements so the<br>
> converted xml becomes part of the training guides during build. The<br>
> conversion script will live in the ./training-guide/sources sub<br>
> directory of the training-manuals sub-project. The converted xml gets<br>
> placed within ./training-guide/sources/<project> directories. The<br>
> conversion script will be run at the same time as when the<br>
> openstack-manuals repo updates are pulled. This will allow the training<br>
> manuals team to find xml content and include it with the training<br>
> guides. If the source RST has a bug, then the RST source will be<br>
> patched, and the XML will get the bug fix through the next run of the<br>
> conversion script.<br>
><br>
> Blueprint<br>
> here <a href="https://blueprints.launchpad.net/openstack-manuals/+spec/rst-xml-conversion" target="_blank">https://blueprints.launchpad.net/openstack-manuals/+spec/rst-xml-conversion</a><br>
> Wiki details<br>
> here <a href="https://wiki.openstack.org/wiki/Training-manuals#RST-XML_Conversion_automation" target="_blank">https://wiki.openstack.org/wiki/Training-manuals#RST-XML_Conversion_automation</a><br>
><br>
> Sean Roberts<br>
> Infrastructure Strategy<br>
</div></div>> <a href="mailto:seanrob@yahoo-inc.com">seanrob@yahoo-inc.com</a> <mailto:<a href="mailto:seanrob@yahoo-inc.com">seanrob@yahoo-inc.com</a>> <a href="tel:%28925%29%20980-4729" value="+19259804729">(925) 980-4729</a><br>
><br>
><br>
><br>
> _______________________________________________<br>
> Openstack-docs mailing list<br>
> <a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
><br>
<br>
<br>
_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</blockquote></div><br><br clear="all"><div><br></div>-- <br>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>
</div>