Open Stack

We discussed Sean's needs at length on IRC earlier today, and I wanted him
to get more input from this list.

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.

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.
For example:

pandoc -f markdown -t docbook -s image-api-v2.0.md |  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
We have discovered some issues with the output from these types of non-XML
starting points.
- In PDF, title doesn't wrap correctly
- Code samples could be resized (smaller) to fit on a page nicely if it
were XML
- Some strange page breaks (which can be better controlled with processing
instructions)
- chunking can be more finely indicated for the HTML output especially

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.

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
https://review.openstack.org/#/c/50509/ until we can revisit after release.

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.

Thanks for bringing it to the list -

Anne


On Wed, Oct 9, 2013 at 7:00 PM, David Cramer <david.cramer at rackspace.com>wrote:

> Hi Sean,
> xslt would be well-suited to cleaning up the output of pandoc and
> converting it to DocBook 5.x. This could be invoked from your python
> script:
>
>
> https://svn.code.sf.net/p/docbook/code/trunk/docbook/relaxng/tools/db4-upgrade.xsl
>
> If you have other cleanup to perform, we could add the necessary logic
> to the db4-upgrade.xsl.
>
> I'll be happy to help with the xslt and I think the result would be more
> robust.
>
> Regards,
> David
>
> On 10/09/2013 06:37 PM, Sean Roberts wrote:
> > The training-manuals team is proposing a blueprint to implement rst to
> > xml conversion script. This code is used to convert devref project rst
> > documentation into xml that the openstack manuals project can use. The
> > Training-manuals sub-project will use xi:include statements so the
> > converted xml becomes part of the training guides during build. The
> > conversion script will live in the ./training-guide/sources sub
> > directory of the training-manuals sub-project. The converted xml gets
> > placed within ./training-guide/sources/<project> directories. The
> > conversion script will be run at the same time as when the
> > openstack-manuals repo updates are pulled. This will allow the training
> > manuals team to find xml content and include it with the training
> > guides. If the source RST has a bug, then the RST source will be
> > patched, and the XML will get the bug fix through the next run of the
> > conversion script.
> >
> > Blueprint
> > here
> https://blueprints.launchpad.net/openstack-manuals/+spec/rst-xml-conversion
> > Wiki details
> > here
> https://wiki.openstack.org/wiki/Training-manuals#RST-XML_Conversion_automation
> >
> > Sean Roberts
> > Infrastructure Strategy
> > seanrob at yahoo-inc.com <mailto:seanrob at yahoo-inc.com> (925) 980-4729
> >
> >
> >
> > _______________________________________________
> > Openstack-docs mailing list
> > Openstack-docs at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> >
>
>
> _______________________________________________
> Openstack-docs mailing list
> Openstack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>



-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131009/9c4df534/attachment-0001.html>