Copy editing documentation - SOC project
Matthias Schabel <boost@schabel-family.org> wrote:
FYI, QuickBook already has the reverse-lit feature. It lets you "import" code snippets from actual code. Rene and I are using it right now to great effect.
I have to say, as a non-CS person, I'm finding it hard to even keep track of the differences between DocBook, BoostBook, and QuickBook, much less figure out how to accomplish anything with them... Just as a side note, given that documentation is already generally regarded as one of the most painful parts of library development, I think it would be a good idea for Boost to standardize on one system or another and then provide a good tutorial on how to use it... For example, after browsing all the QuickBook documentation I could find, I still have no idea how to implement the code snippet import feature you described;
After working with Gennadiy to copy edit some documentation I'd have to agree. Everyone has there own preference, Word, Docbook, Latex etc. but you need some common standard if your going to working collaboratively on documentation, ideally it should be a format the preserves markup in some explicit way. I know it might be an unpopular suggestion, but have you thought of moving the Boost documentation to a wiki based system? Even if only certain members are provided access I think it would be better than what you currently have, most people are happy enough learning to edit text in a wiki. Googling even gives some information on a wiki to DocBook converter... http://www.tldp.org/wt2db/
furthermore, as far as I can tell, there is no .qbk source in Boost (from recent CVS-HEAD) that I could use to try to emulate your Spirit documentation (assuming that is the documentation that uses this reverse-lit import, which I can't know a priori). Finally, while there appears to be some way to have DocBook output LaTeX, it isn't clear to me that there is any way to have it parse and process LaTeX source in, for example, the way that Doxygen does so that you can get images of typeset equations in the HTML output. Maybe it's possible, but it is certainly far from obvious, and the amount of time I would have to invest learning a completely new system hardly seems to justify the potential benefit. Anyway, sorry for the rant - it just doesn't seem like this should be this painful...
Matthias
Nava Whiteford wrote:
Matthias Schabel <boost@schabel-family.org> wrote:
FYI, QuickBook already has the reverse-lit feature. It lets you "import" code snippets from actual code. Rene and I are using it right now to great effect. I have to say, as a non-CS person, I'm finding it hard to even keep track of the differences between DocBook, BoostBook, and QuickBook, much less figure out how to accomplish anything with them... Just as a side note, given that documentation is already generally regarded as one of the most painful parts of library development, I think it would be a good idea for Boost to standardize on one system or another and then provide a good tutorial on how to use it... For example, after browsing all the QuickBook documentation I could find, I still have no idea how to implement the code snippet import feature you described;
After working with Gennadiy to copy edit some documentation I'd have to agree. Everyone has there own preference, Word, Docbook, Latex etc. but you need some common standard if your going to working collaboratively on documentation, ideally it should be a format the preserves markup in some explicit way.
I'm confused. What are you agreeing on? Are you using BoostBook/ QuickBook? Matthias post is about QuickBook. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Nava Whiteford Sent: 12 March 2007 13:22 To: boost@lists.boost.org Subject: [boost] Copy editing documentation - SOC project
Matthias Schabel <boost@schabel-family.org> wrote:
FYI, QuickBook already has the reverse-lit feature. It lets you "import" code snippets from actual code. Rene and I are using it right now to great effect.
I have to say, as a non-CS person, I'm finding it hard to even keep track of the differences between DocBook, BoostBook, and QuickBook, much less figure out how to accomplish anything with them... Just as a side note, given that documentation is already generally regarded as one of the most painful parts of library development, I think it would be a good idea for Boost to standardize on one system or another and then provide a good tutorial on how to use it... For example, after browsing all the QuickBook documentation I could find, I still have no idea how to implement the code snippet import feature you described;
After working with Gennadiy to copy edit some documentation I'd have to agree. Everyone has there own preference, Word, Docbook, Latex etc. but you need some common standard if your going to working collaboratively on documentation, ideally it should be a format the preserves markup in some explicit way.
I know it might be an unpopular suggestion, but have you thought of moving the Boost documentation to a wiki based system?
Quickbook is very close the Wikipedia markup language, so it can be used as easily. CVS already allows control over who can edit it - avoiding the spamming that would certainly be a problem judging by Boosts current wikis. I would suggest that we put draft documents up on CVS (SVN later?) for general editing, and permit the original author to reject edits before posting his preferred version for each formal release. I suspect people will just add their extra bits and correct the typos and it will work smoothly - few things are really contentious - unlike some Wikipedia subject areas. The problem is to get existing documents like Boost.Test into Quickbook. A re-write would be a good time to do this - otherwise it is a major task. Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
I'm sorry that I haven't followed this discussion closely or spoken up sooner. I'll just say that 'editing documentation' is *NOT* a valid SoC project -- unless the rules have changed since last year. Google was quite clear on this -- the project needs to involve coding. Jeff
The original post suggested that developing/refining the Boost documentation tools might be a reasonable SOC project, not editing documentation. The subject line is misleading... Matthias
I'm sorry that I haven't followed this discussion closely or spoken up sooner. I'll just say that 'editing documentation' is *NOT* a valid SoC project -- unless the rules have changed since last year. Google was quite clear on this -- the project needs to involve coding.
Jeff _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/ listinfo.cgi/boost
Jeff Garland wrote:
I'm sorry that I haven't followed this discussion closely or spoken up sooner. I'll just say that 'editing documentation' is *NOT* a valid SoC project -- unless the rules have changed since last year. Google was quite clear on this -- the project needs to involve coding.
How about beefing up our documentation tools? Make it easier to install configure and use, make it seamlessly generate nice PDF without the hassles of FOP (e.g. http://dblatex.sourceforge.net/examples.html), etc? Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel de Guzman wrote:
Jeff Garland wrote:
I'm sorry that I haven't followed this discussion closely or spoken up sooner. I'll just say that 'editing documentation' is *NOT* a valid SoC project -- unless the rules have changed since last year. Google was quite clear on this -- the project needs to involve coding.
How about beefing up our documentation tools? Make it easier to install configure and use, make it seamlessly generate nice PDF without the hassles of FOP (e.g. http://dblatex.sourceforge.net/examples.html), etc?
As long as there is coding it's fine. Scripting a 'build' and setup process is still coding. Jeff
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Joel de Guzman Sent: 12 March 2007 16:25 To: boost@lists.boost.org Subject: Re: [boost] Copy editing documentation - SOC project
How about beefing up our documentation tools? Make it easier to install configure and use, make it seamlessly generate nice PDF without the hassles of FOP (e.g. http://dblatex.sourceforge.net/examples.html), etc?
Neat ! But Quickbook seems to me to meet the needs of Boost-type stuff very nicely. (and once setup - the tricky bit - is virtually the same as Docbook etc). Or does it need some work on it still? Except that the conversion to pdf didn't work using FOP (but as I recall, for problems with graphics being inefficient for graphics using bitmaps not vectors, and we didn't manage the equations in MathML rather than intrinsic problems?) And it doesn't produce an automatic INDEX, as well as a Table of Contents. So how can we produce a GSoC project out of this? Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
Paul A Bristow wrote:
How about beefing up our documentation tools? Make it easier to install configure and use, make it seamlessly generate nice PDF without the hassles of FOP (e.g. http://dblatex.sourceforge.net/examples.html), etc?
Neat !
Before we get too carried away, there are still plenty of issues with DocBook to latex conversion: tables with code in them get particularly badly mangled as I recall. Ultimately every time you change formats you loose something :-(
But Quickbook seems to me to meet the needs of Boost-type stuff very nicely. (and once setup - the tricky bit - is virtually the same as Docbook etc).
Or does it need some work on it still?
We could really use someone to figure out all the installation stuff, document it, and write some Unix and windows installer scripts.
Except that the conversion to pdf didn't work using FOP (but as I recall, for problems with graphics being inefficient for graphics using bitmaps not vectors, and we didn't manage the equations in MathML rather than intrinsic problems?)
Basically FOP sucks. I'm sorry, but it's my opinion and I'm sticking to it! The interesting thing is the commercial alternative (RenderX) works very well, so clearly it can be done. Sadly writing a complete docbook->pdf converter in three months sounds a bit ambitious - pity 'cos I bet a lot of projects besides Boost could use it.
And it doesn't produce an automatic INDEX, as well as a Table of Contents.
Modifying quickbook to take a concordance file and produce propper docbook indexes shouldn't be too hard? Then we just need to rely on the docbook toolchains doing something meaningful with the data...
So how can we produce a GSoC project out of this?
So... installation scripts, documentation, and index generation. Is that enough to be a project? Oh wait we could at IDE integration as well, and let's not forget that Matias got started on some of this last year: http://cablemodem.fibertel.com.ar/mcape/oss/projects/mc_projects/boost_proje..., looks like not much has been started but the logos and code name are nice anyway :-) John.
John Maddock wrote:
Paul A Bristow wrote:
How about beefing up our documentation tools? Make it easier to install configure and use, make it seamlessly generate nice PDF without the hassles of FOP (e.g. http://dblatex.sourceforge.net/examples.html), etc? Neat !
Before we get too carried away, there are still plenty of issues with DocBook to latex conversion: tables with code in them get particularly badly mangled as I recall. Ultimately every time you change formats you loose something :-(
Oh. And we have a lot of those.
But Quickbook seems to me to meet the needs of Boost-type stuff very nicely. (and once setup - the tricky bit - is virtually the same as Docbook etc).
Or does it need some work on it still?
We could really use someone to figure out all the installation stuff, document it, and write some Unix and windows installer scripts.
Rene already started a Windows installer script.
Except that the conversion to pdf didn't work using FOP (but as I recall, for problems with graphics being inefficient for graphics using bitmaps not vectors, and we didn't manage the equations in MathML rather than intrinsic problems?)
Basically FOP sucks. I'm sorry, but it's my opinion and I'm sticking to it! The interesting thing is the commercial alternative (RenderX) works very well, so clearly it can be done.
Sadly writing a complete docbook->pdf converter in three months sounds a bit ambitious - pity 'cos I bet a lot of projects besides Boost could use it.
Too ambitious, IMO.
And it doesn't produce an automatic INDEX, as well as a Table of Contents.
Modifying quickbook to take a concordance file and produce propper docbook indexes shouldn't be too hard? Then we just need to rely on the docbook toolchains doing something meaningful with the data...
Not hard. I know what to do. It's just a matter of doing it.
So how can we produce a GSoC project out of this?
So... installation scripts, documentation, and index generation. Is that enough to be a project? Oh wait we could at IDE integration as well, and let's not forget that Matias got started on some of this last year: http://cablemodem.fibertel.com.ar/mcape/oss/projects/mc_projects/boost_proje..., looks like not much has been started but the logos and code name are nice anyway :-)
..Also, make it usable for non-boost documentation. It's a generally useful tool. Address the qualms of Dave A :) Have the toolset hook (optionally) to python (to take advantage of Dave's work on LiTre). Use regex for the syntax highlighter (so we can plug in highilghers for other languages). I can come up with a list of things needed to be done. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel de Guzman wrote:
..Also, make it usable for non-boost documentation. It's a generally useful tool. Address the qualms of Dave A :) Have the toolset hook (optionally) to python (to take advantage of Dave's work on LiTre). Use regex for the syntax highlighter (so we can plug in highilghers for other languages). I can come up with a list of things needed to be done.
OK, I've added it as a project suggestion to the Wiki, feel free to edit as you see fit :-) John.
on Mon Mar 12 2007, "John Maddock" <john-AT-johnmaddock.co.uk> wrote:
Except that the conversion to pdf didn't work using FOP (but as I recall, for problems with graphics being inefficient for graphics using bitmaps not vectors, and we didn't manage the equations in MathML rather than intrinsic problems?)
Basically FOP sucks. I'm sorry, but it's my opinion and I'm sticking to it! The interesting thing is the commercial alternative (RenderX) works very well, so clearly it can be done.
Sadly writing a complete docbook->pdf converter in three months sounds a bit ambitious - pity 'cos I bet a lot of projects besides Boost could use it.
It's not that hard if you go through LaTeX. You just need a converter from docbook (the QB output format) to LaTeX, and pdflatex does the rest. And it's pretty easy to make this work on Windows under Cygwin, too. -- Dave Abrahams Boost Consulting www.boost-consulting.com
on Mon Mar 12 2007, Nava Whiteford <nwhiteford-AT-tchpc.tcd.ie> wrote:
most people are happy enough learning to edit text in a wiki
Personally, I hate it. I am effective with emacs, and I want revision control on my documentation text, so unless the wiki changes somehow resulted in changes to an SVN repository whose source I could edit another way, I would find it uncomfortable. The good of the community should of course win out over my discomfort, if a wiki would indeed be better, but I'm not yet convinced it would be. -- Dave Abrahams Boost Consulting www.boost-consulting.com
On Thu, 15 Mar 2007 21:16:22 -0000, David Abrahams <dave@boost-consulting.com> wrote:
Personally, I hate it. I am effective with emacs, and I want revision control on my documentation text, so unless the wiki changes somehow resulted in changes to an SVN repository whose source I could edit another way, I would find it uncomfortable.
Ikiwiki (http://ikiwiki.info/) uses subversion, although I've never used it. I think there's other wiki software which does as well. Daniel
participants (8)
-
Daniel James -
David Abrahams -
Jeff Garland -
Joel de Guzman -
John Maddock -
Matthias Schabel -
Nava Whiteford -
Paul A Bristow