search

robert-strandh / CL-reference

Reference manual for the Common Lisp programming language.
17 stars 2 forks source link

Why not Asciidoc? #2

Open hijarian opened 9 years ago

hijarian commented 9 years ago

There is a lightweight markup language which is probably superior to LaTeX in the domain of technical programming documentation, and it's AsciiDoc, in it's current incarnation called Asciidoctor. As this project is in the very beginning, maybe it's not late to change to that markup? It's a lot simpler than LaTeX and has native conversion to HTML and directly to PDF.

robert-strandh commented 9 years ago

I would have to think about that.

The problem I have for every project similar to this one is that the markup language is what people have the most opinions about. There seems to be no way to get it right for everyone.

What I would really want to do is to have a set of protocols for managing documents as CLOS classes and generic functions. That way, people can choose whatever way they want in order to create a document, and we would have well-defined ways of manipulating it.

Most markup languages define only the markup language, and they supply software to convert to other formats or to produce printed output. But they usually do not define how the documents can be manipulated once read. And even if they did, it would probably not be in the form of CLOS classes.

hijarian commented 9 years ago

@robert-strandh I have seen common-doc project which I think is quite promising in solving problem of common documentation format. An AsciiDoc to CommonDoc parser can be potentially built and the reason for CommonDoc itself is that we can consistently export to anything - latex or maybe PDF directly, HTML, plaintext, Markdown, texinfo, whatever.

I must say that it's neither a feature request (I am not arrogant enough) nor a personal offer before a pull request (I am working on other stuff these days). I see a great value in this project, but firsthand experience writing and reading LaTex tells me that the lightweight markup formats clearly win in both readability and maintainability.

AsciiDoc allows extending it with new commands, so I suspect there will be no decrease in expressiveness, and it is 1:1 mapped to DocBook, a vocabulary specifically designed to express technical literature. It's only lacking the toolset.

So, if you haven't seen those technologies before, here they are. Now you know. ;)

robert-strandh commented 9 years ago

Yes, common-doc was a direct result of a discussion on #lisp in which I expressed the desire for a document format defined as a collection of CLOS protocols.

I think it is time that I take a look at it again.

Notice that I am not arguing about the relative technical merits of various markup languages, and I am perfectly willing to accept your conclusion that lightweight markup formats are superior to LaTeX. I am just saying that the very concept of defining what can be done with a document as a markup language and translations to other formats is flawed. Given that people have strong feelings about the markup language, and that those feelings are not based on technical merits, choosing a particular markup language is bound to discourage a large number of potential contributors, no matter the choice. Your comments are immediate evidence for my thinking that; my choosing LaTeX triggered this reaction from you after all.

hijarian commented 9 years ago

my choosing LaTeX triggered this reaction from you after all.

:)

Also I remember the recent flame war about esr's proposal to change all of Emacs documentation from texinfo to AsciiDoc. :)

I personally not strictly against the LaTeX; I have marked up quite a lot of documents with it. I just know for sure that LaTeX sources of any reasonable complexity (cl-reference is an example itself) quickly become very hard to read in raw, it's impossible to deny. And hard to read => hard to maintain. LaTeX has a superior amount of tools in its infrastructure, though.