On Fri, 23 Sep 2016 15:31:22 +0200 Bára Ančincová <bara@xxxxxxxxxx> wrote: > On 09/22/2016 12:38 AM, Alfredo Deza wrote: > > On Tue, Sep 20, 2016 at 7:25 AM, John Spray <jspray@xxxxxxxxxx> wrote: > >> Hi all, > >> > >> Currently the Ceph upstream documentation is mostly written in > >> restructuredtext, and built into HTML with Sphinx. > >> > >> We at Red Hat have some writer colleagues who are more comfortable > >> with asciidoc, and it has been suggested that we could get more new > >> content upstream (i.e. on github for everyone) if we were using > >> asciidoc. > > > > The barrier to contribute from asciidoc to rst is not huge, it is > > mainly inconvenient. I think there is much more to gain > > from current contributors to raise the bar to improve the current state of docs. > > > >> > >> So does anyone have any strong attachment to the restructuredtext > >> format currently in use? > > > > I really like RestructuredText, but an important question here is: > > *if* we decided to move, are we aware of the burden that means > > to generate: html, man pages, and the porting of the extensions > > (doxygen, ditaa, and maybe something else I might be missing) > > Another solution I can think of is to enhance pandoc (or some other > converter) to be able to convert between RST and AsciiDoc reliably, > without the need to manually edit the files afterwards. > > I recently found out that one of my colleagues (Petr Kovar, cc'ed) is > dealing with the same problem. He contributes to the OpenStack upstream > docs. Maybe we can join forces. Thanks for looping me in, Bara. The RHOSP team is trying to semi-automate downstreaming some of the OpenStack upstream guides, which are apparently using the same publishing toolchain (RST + Sphinx) as the Ceph upstream. The problem is that support for RST markup in pandoc is currently incomplete, which makes the whole process very fragile. I'd be very much interested in working together on finding a robust enough solution for RST to adoc conversion if that's what you decide to go with for your upstream to downstream content flow. Thanks, pk -- Petr Kovar Sr. Technical Writer | Customer Content Services Red Hat Czech, Brno -- To unsubscribe from this list: send the line "unsubscribe ceph-devel" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
