search

dsheets / codoc

OCaml documentation generator
34 stars 5 forks source link

Question: Why XML instead of JSON #63

Closed jordwalke closed 9 years ago

jordwalke commented 9 years ago

JSON seems like an easier format to manipulate and integrate into web renderers. I don't think it matters too much, but just curious what the reasoning was.

dbuenzli commented 9 years ago

Not speaking on behalf of the authors but for once XML is used for what it has been designed for... Why put document markup data in JSON string members when you have a format that's precisely designed to handle that ? Why deal with two data formats when you can solve the problem naturally with one ?

dsheets commented 9 years ago

@dbuenzli has got it. Documentation is really about marked up documents which may contain multiple different markup languages (OCaml docs, HTML, indexes, etc). We pre-render HTML and serve it directly and so avoid all JavaScript in the browser. We use xmlm via cow to render so we already have this as a dependency.

If you're interested in a JSON representation, I'm sure a JSON codec on top of doc-ock-lib would be useful.