RE: [Haskell] Making Haskell more open
On 11 November 2005 12:57, Wolfgang Jeltsch wrote:
Am Donnerstag, 10. November 2005 12:27 schrieb Simon Peyton-Jones:
[...]
- Work is afoot to move GHC's source-code repository to Darcs, to make it easier for people to contribute patches
Is it planned to split the current big monolithic repository into multiple repositories in conjunction with doing the CVS-to-darcs transition? I'd strongly recommend this. What do others think?
We do plan to split the repository into several chunks, and over time some of the libraries will migrate into their own repositories. Here is the current plan: http://www.haskell.org//pipermail/cvs-ghc/2005-November/027174.html
[...]
* The GHC user manual [currently generated using DocBook]
I think it should continue to be written in DocBook. (It should switch to DocBook XML if it's still using SGML DocBook.) XML documents are "type-safe" in contrast to LaTeX documents, for example. XML is well supported. DocBook stresses logical markup and allows very specific markup and therefore supports conversion into different formats (HTML, PDF, ...) very well. Again, what do others think?
We already use DocBook XML, and I'm relatively pleased with it, except for the fact that it's far from easy to set up a working DocBook toolchain on your system unless your OS of choice is up to date and has a well-maintained set of DocBook packages. Cheers, Simon
Hello Simon, Friday, November 11, 2005, 5:51:55 PM, you wrote:
* The GHC user manual [currently generated using DocBook]
I think it should continue to be written in DocBook. (It should switch to DocBook XML if it's still using SGML DocBook.) XML documents are "type-safe" in contrast to LaTeX documents, for example. XML is well supported. DocBook stresses logical markup and allows very specific markup and therefore supports conversion into different formats (HTML, PDF, ...) very well. Again, what do others think?
SM> We already use DocBook XML, and I'm relatively pleased with it, except SM> for the fact that it's far from easy to set up a working DocBook SM> toolchain on your system unless your OS of choice is up to date and has SM> a well-maintained set of DocBook packages. how it will be possible to contribute in ghc docs? for example, if i wrote template haskell doc in MS Word, can i fo somethong to make it ready to including in ghc docs? -- Best regards, Bulat mailto:bulatz@HotPOP.com
Simon Marlow (simonmar@microsoft.com) wrote:
We already use DocBook XML, and I'm relatively pleased with it, except for the fact that it's far from easy to set up a working DocBook toolchain on your system unless your OS of choice is up to date and has a well-maintained set of DocBook packages.
I consider that the structure of the present ghc manual does not need such a rich markup as DocBook which is, imho, not very user-friendly. otoh, I'd prefer something simple (if you want to get contributions from more users) like 'txt2tags' (see e.g. http://txt2tags.sourceforge.net/screenshots.html) which enables one to do lot with very simple markup. There are many targets supported, light sys-reqs, cli & gui, and even syntax highlighting for (g)vim, emacs, kate... Sincerely, Gour -- Registered Linux User | #278493 GPG Public Key | 8C44EDCD
I agree with Gour. I found txt2tags as a result of a discussion on the GTK2HS list. It is simple to use, readable as is, or easily transformable to a variety of targets. Also, it is consistent with bird-track literate Haskell, so I can run my .lhs documents through txt2tags and get html, latex, pretty text, or a bunch of things I haven't tried yet including *.doc (msword) (the latter via txt2tags for html, soffice to go from html to *.doc). John Velman On Fri, Nov 11, 2005 at 06:29:24PM +0100, Gour wrote:
Simon Marlow (simonmar@microsoft.com) wrote:
We already use DocBook XML, and I'm relatively pleased with it, except for the fact that it's far from easy to set up a working DocBook toolchain on your system unless your OS of choice is up to date and has a well-maintained set of DocBook packages.
I consider that the structure of the present ghc manual does not need such a rich markup as DocBook which is, imho, not very user-friendly.
otoh, I'd prefer something simple (if you want to get contributions from more users) like 'txt2tags'
(see e.g. http://txt2tags.sourceforge.net/screenshots.html)
which enables one to do lot with very simple markup.
There are many targets supported, light sys-reqs, cli & gui, and even syntax highlighting for (g)vim, emacs, kate...
Sincerely, Gour
-- Registered Linux User | #278493 GPG Public Key | 8C44EDCD
_______________________________________________ Haskell mailing list Haskell@haskell.org http://www.haskell.org/mailman/listinfo/haskell
Am Freitag, 11. November 2005 20:08 schrieb John Velman:
I agree with Gour. I found txt2tags as a result of a discussion on the GTK2HS list. It is simple to use, readable as is, or easily transformable to a variety of targets. Also, it is consistent with bird-track literate Haskell, so I can run my .lhs documents through txt2tags and get html, latex, pretty text, or a bunch of things I haven't tried yet including *.doc (msword) (the latter via txt2tags for html, soffice to go from html to *.doc).
The most important question is: Does txt2tags use logical markup?
John Velman
Best wishes, Wolfgang
On Sun, 2005-11-13 at 18:18 +0100, Wolfgang Jeltsch wrote:
Am Freitag, 11. November 2005 20:08 schrieb John Velman:
I agree with Gour. I found txt2tags as a result of a discussion on the GTK2HS list. It is simple to use, readable as is, or easily transformable to a variety of targets. Also, it is consistent with bird-track literate Haskell, so I can run my .lhs documents through txt2tags and get html, latex, pretty text, or a bunch of things I haven't tried yet including *.doc (msword) (the latter via txt2tags for html, soffice to go from html to *.doc).
The most important question is: Does txt2tags use logical markup?
No, it is very layout driven. The advantage is that its dead simple. To be honest we (the Gtk2Hs people) haven't started on our tutorial yet, so we don't have any experience with txt2tags yet. If you think that logical markup is important, then I'd like to point out that DocBook gives you some structure, but you still put in some meaning on top of that, i.e. DocBook has extensive markup for specifying C function signatures, but you'd have to extend it to give you anything that goes beyond pure layout information for things like Haskell functions or code snippets. I think the right thing is to keep ghc's manual in DocBook. What people add will not be whole chapters, but rather paragraphs. The markup you need to learn for that can easily be gleamed from the surrounding text. Axel.
Am Sonntag, 13. November 2005 19:11 schrieben Sie:
On Sun, 2005-11-13 at 18:18 +0100, Wolfgang Jeltsch wrote: [...]
The most important question is: Does txt2tags use logical markup?
No, it is very layout driven.
So then I would strongly recommend to *not* use it.
[...]
If you think that logical markup is important, then I'd like to point out that DocBook gives you some structure, but you still put in some meaning on top of that, i.e. DocBook has extensive markup for specifying C function signatures, but you'd have to extend it to give you anything that goes beyond pure layout information for things like Haskell functions or code snippets.
That's true. Well, being able to mark up parts of Haskell code like identifiers or type declarations is not too important to me at the moment. But I definitely think that one should be able to say: "This is emphasized text." or: "This is code." instead of being forced to say: "This should be typeset in italics." or: "This should be typeset in typewriter font on a separate paragraph with indentation."
[...]
Best wishes, Wolfgang
Am Freitag, 11. November 2005 15:51 schrieb Simon Marlow:
[...] We already use DocBook XML, and I'm relatively pleased with it, except for the fact that it's far from easy to set up a working DocBook toolchain on your system unless your OS of choice is up to date and has a well-maintained set of DocBook packages.
As I'm guilty of kicking out the old SGML stuff and introducing DocBook XML, I'd like to add two remarks: * DocBook XML can be transformed into a very rich collection of output formats: XHTML, HTML Help, DVI, PS, PDF, FO, plain text, etc. etc. * 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. (On a related note, this is one of my major concerns about the introduction of darcs, but I'll be happy if I'm proven wrong...) Cheers, S.
Am Sonntag, 13. November 2005 20:29 schrieb Sven Panne:
[...]
As I'm guilty of kicking out the old SGML stuff and introducing DocBook XML, I'd like to add two remarks:
* DocBook XML can be transformed into a very rich collection of output formats: XHTML, HTML Help, DVI, PS, PDF, FO, plain text, etc. etc.
Very right.
* 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. (On a related note, this is one of my major concerns about the introduction of darcs, but I'll be happy if I'm proven wrong...)
So then, let's stop using Haskell. :-) Honestly, caring too much about how much a certain "technology" is known and used will kill innovation. If something new is really better than what's already there then I want to consider its adoption. Compatibilty, support and the like is also important but it shouldn't be overrated. I don't like it when creativity and true innovation is hindered too much by pragmatic arguments. Nevertheless, I could imagine that DocBook XML does a better job for the GHC documentation than the other things proposed.
Cheers, S.
Best wishes, Wolfgang
participants (7)
-
Axel Simon -
Bulat Ziganshin -
Gour -
John Velman -
Simon Marlow -
Sven Panne -
Wolfgang Jeltsch