Re: [Haskell] Making Haskell more open

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
15 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: [Haskell] Making Haskell more open

Gour-2
Wolfgang Jeltsch ([hidden email]) wrote:

> In addition, one could argue that since newsgroups were specifically
> designed for discussions, newsgroup software allows proper mangagement
> of threads but, well, current e-mail programs might do this in similar
> quality.

>From the most plain mailers like pine & mutt, to the gui-mailers (kmail,
evolution), all have threading support.

Sincerely,
Gour

p.s. I am moving this reply to cafe.

--
Registered Linux User | #278493
GPG Public Key | 8C44EDCD
 
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: [Haskell] Making Haskell more open

Gour-2
Wolfgang Jeltsch ([hidden email]) wrote:

> The most important question is: Does txt2tags use logical markup?

A kind of, e.g.

= title =
== subtitle ==
=== subsub...===

if this is logical ;)

Sincerely,
Gour

--
Registered Linux User | #278493
GPG Public Key | 8C44EDCD
 
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: [Haskell] Making Haskell more open

Gour-2
In reply to this post by Gour-2
Wolfgang Jeltsch ([hidden email]) wrote:

> The font size is much smaller than the font size of other webpages.  So if I
> would change the default font size to give good results with the Haskell
> website, all other websites would have their text in very large letters.

Well, haskell.org has smaller font size for the links, but the my
preferred portal site (www.iskon.hr) has even smaller.

However, pressing 'Ctrl +' to increase font size is, imoho, not such a
big task :-)

> The question is if HTML is sufficient.  In addition, HTML is at some points
> not well thought-out.

True, but considering the present situation, it is all what is required.

Sincerely,
Gour

--
Registered Linux User | #278493
GPG Public Key | 8C44EDCD
 
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: [Haskell] Making Haskell more open

Sven Panne
Am Sonntag, 13. November 2005 22:05 schrieb Gour:
> Wolfgang Jeltsch ([hidden email]) wrote:
>[...]
> > The question is if HTML is sufficient.  In addition, HTML is at some
> > points not well thought-out.
>
> True, but considering the present situation, it is all what is required.

Well, that's a wrong assumption: People on Windows will expect HTML Help, and
the current build system can easily generate this from DocBook XML. I think
the current installers/ZIP files for GHC and the other tools don't include
HTML Help, but I consider this a packaging bug.

Cheers,
   S.
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: [Haskell] Making Haskell more open

Gour-2
In reply to this post by Gour-2
Sven Panne ([hidden email]) 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
 
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: [Haskell] Making Haskell more open

Sven Panne
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... >:-)
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: [Haskell] Making Haskell more open

Krasimir Angelov-2
In reply to this post by Gour-2
2005/11/13, Gour <[hidden email]>:
> Sven Panne ([hidden email]) 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
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: [Haskell] Making Haskell more open

Gour-2
In reply to this post by Sven Panne
Sven Panne ([hidden email]) 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
 
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: [Haskell] Making Haskell more open

Ketil Malde
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
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: [Haskell] Making Haskell more open

Wolfgang Jeltsch
In reply to this post by Gour-2
Am Sonntag, 13. November 2005 22:05 schrieb Gour:
> [...]

> > The question is if HTML is sufficient.  In addition, HTML is at some
> > points not well thought-out.
>
> True, but considering the present situation, it is all what is required.

I doubt this.  How, for example, do you implement code snippets which should
be rendered in a paragraph of their own in HTML?

> Sincerely,
> Gour

Best wishes,
Wolfgang
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: [Haskell] Making Haskell more open

Wolfgang Jeltsch
In reply to this post by Gour-2
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
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: [Haskell] Making Haskell more open

Duncan Coutts
In reply to this post by Wolfgang Jeltsch
On Mon, 2005-11-14 at 11:03 +0100, Wolfgang Jeltsch wrote:

> Am Sonntag, 13. November 2005 22:05 schrieb Gour:
> > [...]
>
> > > The question is if HTML is sufficient.  In addition, HTML is at some
> > > points not well thought-out.
> >
> > True, but considering the present situation, it is all what is required.
>
> I doubt this.  How, for example, do you implement code snippets which should
> be rendered in a paragraph of their own in HTML?

I wrote a program (based on HsColour by Malcolm Wallace) which processes
xhtml and modifies <code>...</code> blocks to do simple Haskell syntax
highlighting and link function names to corresponding haddock
documentation (by reading .hi file to get the fully qualified names).

http://haskell.org/gtk2hs/darcs/gtk2hs/docs/tools/AddLinks.hs
http://haskell.org/gtk2hs/darcs/gtk2hs/docs/tutorial/Makefile

I'm planning to use it for writing Gtk2Hs tutorials.
http://haskell.org/~duncan/gtk2hs/HelloWorld.xhtml

Duncan

_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: [Haskell] Making Haskell more open

Wolfgang Jeltsch
In reply to this post by Ketil Malde
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
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

Re: Re: [Haskell] Making Haskell more open

Ketil Malde
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
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe
Reply | Threaded
Open this post in threaded view
|

RE: Re: [Haskell] Making Haskell more open

Simon Marlow
In reply to this post by Gour-2
On 14 November 2005 08:32, 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>
>
> 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.

With regard to the GHC user manual, I don't think the implication above
was that we should change the markup technology (at least, I agree with
Sven that DocBook XML is on the whole a reasonable solution).  

The idea was to make it easy for Joe Programmer to add his comments to
the manual, whether by a wiki link or some other clever user-editable
content mechanism.  In a separate stage the comments could be
incorporated into the manual proper by the developers, or just left in
place for the edification of other users.

Cheers,
        Simon
_______________________________________________
Haskell-Cafe mailing list
[hidden email]
http://www.haskell.org/mailman/listinfo/haskell-cafe