Re: [Haskell] Making Haskell more open
Sven Panne (Sven.Panne@aedion.de) wrote:
* DocBook XML can be transformed into a very rich collection of output formats: XHTML, HTML Help, DVI, PS, PDF, FO, plain text, etc. etc.
txt2tags has the following backends: HTML, XHTML, SGML, LaTeX, Lout, man, Magic Point, Moin Moin, Page Maker 6.0 & plain text.
* But what's more important: Compared to the more exotic markup mechanisms proposed, it is well-known and extremely well documented. There are tons of web sites, books, articles, etc. etc. about DocBook XML. Proposing more arcane technologies will drastically reduce the amount of people actually contributing to an Open Source project, a fact which is easily overlooked.
But don't forget, as it was already stated, get the whole working-chain ready for authoring in Docbook is not at all ready and for one not proficient in emacs with SGML mode it is very difficult to write texts with so many tags. otoh, e.g. for 'txt2tags' python is the only requirement and it is therefore multi-platform soulution where one can start writing documentation in 15min. Besides that, 'txt2tags-like technology' is already in use for some time - e.g AFT (http://www.maplefish.com/todd/aft.html) dating back in '99 and XMLmind XML Editor has plugin which supports (similar) markup called APT (http://www.xmlmind.com/xmleditor/_distrib/doc/apt/apt_format.html) quote: "Aptconvert is an OpenSource command-line tool that can be used to convert the APT format to HTML, XHTML, PDF, PostScript, (MS Word loadable) RTF, DocBook SGML and DocBook XML." However, the main point in using such tool is productivity & simplicity. How many tags from DocBook DTD are actually used in GHC manual and how many of them are required for HTML output? Sincerely, Gour -- Registered Linux User | #278493 GPG Public Key | 8C44EDCD
Am Sonntag, 13. November 2005 22:22 schrieb Gour:
[...] Besides that, 'txt2tags-like technology' is already in use for some time - e.g AFT (http://www.maplefish.com/todd/aft.html) dating back in '99 and XMLmind XML Editor has plugin which supports (similar) markup called APT (http://www.xmlmind.com/xmleditor/_distrib/doc/apt/apt_format.html) [...]
Great! If you have already an XML editor, start writing DocBook now! :-) More seriously: This is again a useless tools discussion, we *are* using DocBook currently and it works fine. The real problem is not the XML format and any XML toolchain, it is the lack of people willing to write documentation. There are enough people in the various fptools projects (including me) who will happily and quickly accept documentation patches, be it in plain text or DocBook. And if we are honest: Whoever will contribute to the GHC/Happy/... documentation with a non-trivial amount of text has very probably suffered through the build process, anyway, and getting the XML tools up and running has been the least problem then... Cheers, S. P.S.: In a Google search, DocBook XML dominated txt2tags by a factor of 29, and an amazon.de search showed 7:0 books... >:-)
Sven Panne (Sven.Panne@aedion.de) wrote:
Great! If you have already an XML editor, start writing DocBook now! :-)
No, I won't :-)
More seriously: This is again a useless tools discussion, we *are* using DocBook currently and it works fine. The real problem is not the XML format and any XML toolchain, it is the lack of people willing to write documentation.
Nobody said that DocBook does not work fine. However let me quote SPJ's message: <quote> However, I still wonder if there are things we could do that would make it easier for people to contribute. Here are two concrete suggestions: ^^^^^^^ - Make it possible for people to add comments, explanations, or questions to * The GHC user manual [currently generated using DocBook] * The Haskell 98 Report The idea would be that anyone could help improve these documents, ^^^^^^^^^^^^^^^^^^^ and that, at least in the case of the GHC user manual, we could use the comments to help clarify the text. </quote> So, the whole discussion, at least from my side, was to offer suggestions to make it easier for more people to contribute to the whole haskell community. For those who are satisfied with the present setup or think that newsgroups are panacea forthe whole problem - fine. My reasoning tells me that Simon is thinking differently and therefore I suggested creating portal site with ticket system with the darcs backend, forums etc. so that new/old users can choose what is best suited for them. So, I wonder how 'txt2tags' produced so much traffic here and the tool uses (almost) the same markup as MoinMoin wiki used for the present HaWiki system (txt2tags even produces MoinMoin output :-)
There are enough people in the various fptools projects (including me) who will happily and quickly accept documentation patches, be it in plain text or DocBook. And if we are honest: Whoever will contribute to the GHC/Happy/... documentation with a non-trivial amount of text has very probably suffered through the build process, anyway, and getting the XML tools up and running has been the least problem then...
Following the same logic, we do not need darcs 'cause " Whoever will contribute to the GHC/Happy/...with a non-trivial amount of.." code "..has very probably suffered through.." using CVS system :-) Thank you for your input. I think that I offered enough 'why' to my suggestion, so there is no need for further "useless tools discussion" ;) Sincerely, Gour
P.S.: In a Google search, DocBook XML dominated txt2tags by a factor of 29, and an amazon.de search showed 7:0 books... >:-)
Hmmm, "DocBook XML" gives ~ 608 000, while txt2tags gives ~ 73 000 which gives factor of: ~8. otoh, LaTeX dominates over DocBook by a factor of ~ 38 :-)) -- Registered Linux User | #278493 GPG Public Key | 8C44EDCD
Gour wrote:
Nobody said that DocBook does not work fine. However let me quote SPJ's message:
<quote> However, I still wonder if there are things we could do that would make it easier for people to contribute. Here are two concrete suggestions: ^^^^^^^ - Make it possible for people to add comments, explanations, or questions to * The GHC user manual [currently generated using DocBook] * The Haskell 98 Report The idea would be that anyone could help improve these documents, ^^^^^^^^^^^^^^^^^^^ and that, at least in the case of the GHC user manual, we could use the comments to help clarify the text. </quote>
I think it would be ideal to provide the documentation on the web as now, but linking to wikified talk pages. Something like Wikipedia, (since MediaWiki was brought up) but perhaps with restricted write access to the "feature" pages, and public access to "talk" pages. The "feature" pages could easily(?) be kept in DocBook, if that makes it easier for producing printed copy etc. I don't know about the technical side, and my experience isn't all that wide, but I find I really like the look and feel of Wikipedia compared to other wikis.
For those who are satisfied with the present setup or think that newsgroups are panacea forthe whole problem - fine.
I think newsgroups are a good alternative/supplement to the mailing lists - that is, for discussion, just like IRC is a good forum for getting immediate help on various things. For documentation and more permanent information, something else is required.
Following the same logic, we do not need darcs 'cause " Whoever will contribute to the GHC/Happy/...with a non-trivial amount of.." code "..has very probably suffered through.." using CVS system :-)
I would agree that the threshold needs to be as low as possible, if you want as many as possible to contribute. -k
Am Montag, 14. November 2005 10:49 schrieb Ketil Malde:
[...]
I think it would be ideal to provide the documentation on the web as now, but linking to wikified talk pages. Something like Wikipedia, (since MediaWiki was brought up) but perhaps with restricted write access to the "feature" pages, and public access to "talk" pages. The "feature" pages could easily(?) be kept in DocBook, if that makes it easier for producing printed copy etc. I don't know about the technical side, and my experience isn't all that wide, but I find I really like the look and feel of Wikipedia compared to other wikis.
Hmm, MediaWiki already supports the concept of discussion pages. But I doubt that it's a good thing to maintain DocBook sources via a wiki. One reason is that you might get into conflicts with wiki syntax. Perhaps a darcs repository would be more appropriate here? But in general I kind of like the wiki approach. Maybe not for everything (for instance, not for the GHC documentation's DocBook sources) but for most of what's currently the Haskell website.
[...]
-k
Best wishes, Wolfgang
Wolfgang Jeltsch wrote:
Hmm, MediaWiki already supports the concept of discussion pages.
Yes, I know. Perhaps I was less than lucid, so to clarify:
But I doubt that it's a good thing to maintain DocBook sources via a wiki.
I think it would be best to keep the documentation in DocBook and generate wiki pages from them, and collect user input in the talk pages and similar. Anything general and important could be back-integrated in the DocBook sources by somebody with more of an admin role. -k
2005/11/13, Gour
Sven Panne (Sven.Panne@aedion.de) wrote:
* DocBook XML can be transformed into a very rich collection of output formats: XHTML, HTML Help, DVI, PS, PDF, FO, plain text, etc. etc.
txt2tags has the following backends: HTML, XHTML, SGML, LaTeX, Lout, man, Magic Point, Moin Moin, Page Maker 6.0 & plain text.
I don't see PDF and HtmlHelp backends here. Of course PDF can be created from LaTeX but this requires doble translation and you will need both txt2tags & LaTeX installed. I spent some time to add support for HtmlHelp in haddock and I am using the HtmlHelp output from DocBook. I don't want to spend more time to learn a new markup and to make the things working with the new tools. I can't see real reasons to switch to new formats. Cheers, Krasimir
Am Sonntag, 13. November 2005 22:22 schrieb Gour:
[...]
But don't forget, as it was already stated, get the whole working-chain ready for authoring in Docbook is not at all ready and for one not proficient in emacs with SGML mode it is very difficult to write texts with so many tags.
You should never use Emacs' SGML mode for authoring DocBook *XML*, nor should you use Emacs' ordinary XML mode. Use nXML, it's a lot better.
[...]
How many tags from DocBook DTD are actually used in GHC manual
What's the problem if only a very little amount of "tags" is used in the GHC manual? This might be an argument *for* using DocBook.
and how many of them are required for HTML output?
I have to stress that HTML is not the only output format which should be supported.
Sincerely, Gour
Best wishes, Wolfgang
participants (5)
-
Gour -
Ketil Malde -
Krasimir Angelov -
Sven Panne -
Wolfgang Jeltsch