2013/11/12 Eric H. Christensen <sparks@xxxxxxxxxxxxxxxxx>: > -----BEGIN PGP SIGNED MESSAGE----- > Hash: SHA512 > > On Mon, Nov 11, 2013 at 04:51:06PM -0700, Pete Travis wrote: >> I've set up a quick demonstration[1] of some software that I think will >> address these concerns, a python application called "Nikola"[2]. I have >> a package review in progress for it, and have already packaged some >> dependencies. Briefly, it takes plain text files with ReStructuredText >> or Markdown and transforms them into fully themed static websites. It >> hooks in to transifex nicely as well. Take a look, you'll find a post >> detailing how the implementation might work, and a post for the kind of >> content I envision putting there. > > I've not been able to fully look into your proposed solution but I wonder if we're not doing a good enough job in making DocBook XML easy. I've found that I will, at the drop of a hat, create a Publican article and start writing things up because it's just easier to output the bits in a sane way. I've tried to use other Markups including ASCIIdoc[tor] and I've not found another solution that's as flexible. > > What happens to all the existing source that we have in DocBook XML? If we start something new can we move our existing code over or will we be supporting multiple code source types? With multiple code source types we'll just end up supporting multiple tools for rendering in the end as we'll never get rid of the old, I suspect. > > I also wonder how we'll handle all the different renderings of the guides. With each guide having four formats and each guide needing to be available for each version of Fedora we will quickly reach a point where it's very difficult to manage all that output. We've actually been down this road before. When we were using Publican 1.x we had to hand spin our website which turned out to be a nightmare. What we see in Publican 2.x is a direct result of 1.x not being scalable. We know that 2.x is only scalable to a point and thus 3.x solutions (SRPMs) being used to maintain that scalability. I'd hate to see us venture down this road all over again, relearning from old mistakes... again. > > I suspect that it may be better to educate people on why DocBook XML is a good solution and how to easily mark up a document. It may also be a good idea to figure out how to improve some of our existing documents as some of their structures make it very difficult to find where things are. Hi, Why don't we have a look at what happens in the JBoss.org space? It seems that a lot of docs, also published through DocBook and Publican, are initially written in Asciidoc. Eric, do you happen to know colleagues in this area who'd be kind enough to share his experience here? Dan Allen, Red Hat employee, and Asciidoc contributor, could be a good option for that. I can also ask Emmanuel Bernard who frequently sits in Paris office if he knows someone in the JBoss community working with this kind of tool. Regards, J. -- Jérôme Fenal -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
