I would appreciate is a few paragraphs in the toplevel haddock page or module that describe the general architecture and layout of the modules, as well as the typical entry points. Since the module system doesn't have a notion of private modules and it's common to re-export symbols, it can be unclear where to start, which modules to look at, and why it is the author chose that particular decomposition for the functions. Overall design and architecture is hard to get out of the code. I think the same goes for each module. It's frustrating when I want to figure out how something works, and each module just has a giant chunk of license copy-paste at the top.

On 13 Sep 2011, at 18:59, Michael Orlitzky wrote:

...

Malcolm Wallace and Colin Runciman's ICFP99 paper functioned well as a tutorial for HaXml when I used it - maybe it is a bit out of date now? HaXml is hardly a dire case.

The paper is out-of-date, so it's worse than useless: you'll waste your time figuring out that it's wrong, and you still won't know how to do anything.

There's not one single example anywhere that just shows you how to read or write a damned XML file. If there were anything approaching a physical manifestation of HaXml, I would've strangled it.

I am the first to admit that HaXml's documentation is not as good as it could be, and I am sorry that you have had a bad experience. One thing I am puzzled about, is just how extremely difficult it must be, to click on "Detailed documentation of the HaXml APIs" from the HaXml homepage, look for a moment until you see "Text.XML.HaXml.Parse" in the list of modules, click on it, and find, right at the top of the page, a function that parses a String into an XML document tree. It is absolutely true that finding the reverse conversion (XML tree to String) is more obscure, being either the two-stage process of first using "Text.XML.HaXml.Pretty" to convert to a Doc, then "Text.PrettyPrint.HughesPJ" to render to a String; or alternatively the one-shot conversion in "Text.XML.HaXml.Verbatim". Neither module name is as clear as it should be for a beginner, but I can't think of better ones. Plus, it requires some knowledge of the ecosystem, for instance that pretty-printing is a common technique for producing textual output. In fact, my wish as a library author would be: please tell me what you, as a beginner to this library, would like to do with it when you first pick it up? Then perhaps I could write a tutorial that answers the questions people actually ask, and tells them how to get the stuff done that they want to do. I have tried writing documentation, but it seems that people do not know how to find, or use it. Navigating an API you do not know is hard. I'd like to signpost it better. Regards, Malcolm

On 09/13/2011 05:15 PM, Malcolm Wallace wrote:

I am the first to admit that HaXml's documentation is not as good as it could be, and I am sorry that you have had a bad experience.

Sorry for the tirade =) That was a while ago, but I definitely felt some sympathy for the guy in the quote.

One thing I am puzzled about, is just how extremely difficult it must be, to click on "Detailed documentation of the HaXml APIs" from the HaXml homepage, look for a moment until you see "Text.XML.HaXml.Parse" in the list of modules, click on it, and find, right at the top of the page, a function that parses a String into an XML document tree.

As someone who just wants to parse an XML file, here's what happens. First, I click on the API docs. I'm presented with a list: * Text o XML + Text.XML.HaXml # Text.XML.HaXml.ByteStringPP # Text.XML.HaXml.Combinators # DtdToHaskell * Text.XML.HaXml.DtdToHaskell.Convert * Text.XML.HaXml.DtdToHaskell.Instance * Text.XML.HaXml.DtdToHaskell.TypeDef # Text.XML.HaXml.Escape # Html * Text.XML.HaXml.Html.Generate * Text.XML.HaXml.Html.Parse * Text.XML.HaXml.Html.ParseLazy * Text.XML.HaXml.Html.Pretty # Text.XML.HaXml.Lex # Text.XML.HaXml.Namespaces # Text.XML.HaXml.OneOfN # Text.XML.HaXml.Parse # Text.XML.HaXml.ParseLazy # Text.XML.HaXml.Posn # Text.XML.HaXml.Pretty # Text.XML.HaXml.SAX # Schema * Text.XML.HaXml.Schema.Environment * Text.XML.HaXml.Schema.HaskellTypeModel * Text.XML.HaXml.Schema.NameConversion * Text.XML.HaXml.Schema.Parse * Text.XML.HaXml.Schema.PrettyHaskell * Text.XML.HaXml.Schema.PrimitiveTypes * Text.XML.HaXml.Schema.Schema * Text.XML.HaXml.Schema.TypeConversion * Text.XML.HaXml.Schema.XSDTypeModel # Text.XML.HaXml.ShowXmlLazy # Text.XML.HaXml.TypeMapping # Text.XML.HaXml.Types # Text.XML.HaXml.Util # Text.XML.HaXml.Validate # Text.XML.HaXml.Verbatim # Text.XML.HaXml.Wrappers # Text.XML.HaXml.XmlContent * Text.XML.HaXml.XmlContent.Haskell * Text.XML.HaXml.XmlContent.Parser # Xtract * Text.XML.HaXml.Xtract.Combinators * Text.XML.HaXml.Xtract.Lex * Text.XML.HaXml.Xtract.Parse Jesus! /You/ know that I want to look in Text.XML.HaXml.Parse, but /I/ don't. Let's say I choose the first link: Text.XML.HaXml. It's a list of modules, along with their documentation. All blank! Hitting the back button. The first thing I notice is that there seems to be specialized parser modules for different content types, e.g. Text.XML.HaXml.Html.Parse. Maybe I want Text.XML.HaXml.Schema.Parse? I mean, I want to parse something with a schema, right? Nope, it's for parsing XSDs. How about Text.XML.HaXml.Util? This looks right... Only a small module containing some helper functions to extract xml content - I would have added this to Types but I've put it into an additional module - to avoid circular references (Verbatim - Types) and it's got a function called docContent which is supposed to "Get the main element of the document..." Great. Its type is, docContent :: i -> Document i -> Content i so now, to have any hope of using this function (or figure out that I'm in the wrong place entirely), I have to go figure out what those types are. Document has one constructor, Document Prolog (SymTab EntityDef) (Element i) [Misc] which leads me to, Prolog (Maybe XMLDecl) [Misc] (Maybe DocTypeDecl) [Misc] XMLDecl VersionInfo (Maybe EncodingDecl) (Maybe SDDecl) type VersionInfo = String newtype EncodingDecl = EncodingDecl String type SDDecl = Bool data Misc = Comment Comment | PI ProcessingInstruction type Comment = String type ProcessingInstruction = (PITarget, String) type PITarget = String data DocTypeDecl = DTD QName (Maybe ExternalID) [MarkupDecl] data QName = N Name | QN Namespace Name type Name = String data Namespace = Namespace {nsPrefix :: String, nsURI :: String} data ExternalID = SYSTEM SystemLiteral | PUBLIC PubidLiteral SystemLiteral newtype SystemLiteral = SystemLiteral String newtype PubidLiteral = PubidLiteral String data MarkupDecl = Element ElementDecl | AttList AttListDecl | Entity EntityDecl | Notation NotationDecl | MarkupMisc Misc data ElementDecl = ElementDecl QName ContentSpec data ContentSpec = EMPTY | ANY | Mixed Mixed | ContentSpec CP ... ... most of which are completely undocumented. I have no idea what any of this stuff means! As a result, I don't know what the 'docContent' function does, or whether or not I'm even looking in the right place. At this point, I'm probably googling for blog entries and wondering why I'm wasting my time when all I really need is a "hello, world" example. If by some miracle I do discover Text.XML.HaXml.Parse.xmlParse (do I want ParseLazy? What's the difference?) I can get myself a Document. Now what? Do I try to understand that giant type hierarchy above? There's nothing else in the Parse module that looks useful. All of the good stuff, it turns out, is in the ambiguously-named Text.XML.HaXml.Combinators. Ok, the paper helps a little bit here, if you want to include a few years of college as a prerequisite for parsing XML. There are some things here that look promising, like 'elm' and 'tag'. However, they all have mysterious types: elm, txt :: CFilter i What's a CFilter? type CFilter i = Content i -> [Content i] The Content type actually contains words I recognize! Awesome! But wait, I don't have Content! I have a Document! How do I get Content out of my Document? Argh... This is bringing back bad memories =)

In fact, my wish as a library author would be: please tell me what you, as a beginner to this library, would like to do with it when you first pick it up? Then perhaps I could write a tutorial that answers the questions people actually ask, and tells them how to get the stuff done that they want to do. I have tried writing documentation, but it seems that people do not know how to find, or use it. Navigating an API you do not know is hard. I'd like to signpost it better.

I was trying to parse user timelines from the Twitter API. I threw away most stuff, but wanted to go through the tree and extract the name, body, date, etc. from the individual entries. What's really missing in my opinion is an overview of how everything fits together, along with examples. There are a couple "big" types that you need to know to use the library. Document, Content, and CFilter come to mind. All of those should be well-documented: * What do they represent? * How do they fit together? * Where can I get them, i.e. what functions produce them? * What can I do with them? The examples don't need to be too complicated. How to read/write a file, how to get an element's name, attributes, and text, etc. Anything is better than nothing. Most of the examples in blog posts and other people's code are out of date; while the differences may be small, a new user has no way of knowing that. GHC is just going to throw a type error that may as well be Chinese.

Malcolm Wallace wrote:

In fact, my wish as a library author would be: please tell me what you, as a beginner to this library, would like to do with it when you first pick it up? Then perhaps I could write a tutorial that answers the questions people actually ask, and tells them how to get the stuff done that they want to do. I have tried writing documentation, but it seems that people do not know how to find, or use it. Navigating an API you do not know is hard. I'd like to signpost it better.

From my experience, people are very good at learning patterns from examples, so a list of simple examples with increasing difficulty or a cookbook-style tutorial work very well. In comparison, learning from general descriptions is much harder and usually done by learning from examples anyway. A case in point might by my own reactive-banana library. http://haskell.org/haskellwiki/Reactive-banana I have extensive haddocks and many examples ranging from simple to complicated http://haskell.org/haskellwiki/Reactive-banana/Examples but so far, I never wrote a tutorial or introductory documentation. Curiously, instead of sending complaints, people send me suggestions and code. I interpret this as a sign that my library is easy to understand (if you know Applicative Functors, that is) even though a key part of the documentation is still missing. Best regards, Heinrich Apfelmus -- http://apfelmus.nfshost.com