Gregg Reynolds <d...@mobileink.com> writes:
>> I think that the counter argument to that is that many other programming
>> languages have a richer documentation system than Clojure, and many
>> programmers use them.
>>
>> To be clear, Clojure's documentation system is an unstructured string,
>> the arglists metadata and (arguably) the private metadata.
>>
>
> I would add comment syntax.  Technically maybe not part of a doc "system",
> but I have yet to meet a comment that doesn't count as documentation in
> some sense.


True, and, to some extent, it inherits the ";" vs ";;" comment
distinction. But, again, there is not structure. This is an unstructured
string also. Compare Emacs Lisp, for example, which uses semi-structure
in the comments to drive many of its features.

>> Trivial things that I would like to be able to do that I cannot do (in a
>> way which will be reliably interpreted).
>>
>>  - Add hyperlinks
>>  - Distinguish between symbols (or names of vars) and normal words.
>>  - Distinguish between code (examples) and normal words
>>  - Have access to basic "markdown" style typography.
>>
>
> I'm undecided on these.  They would obviously be useful, but on the other
> hand minimalism has its virtues.  In the base case of reading code with a
> plaintext editor, I usually find embedded doco with lots of markup annoying
> and an impediment to code reading.  I think I'm inclined to favor keeping
> markup out of code but I'm keeping an open mind about it.

I've used this example before; consider this unstructured string from
`cons`.

Returns a new seq where x is the first element and seq is
the rest.


So, cons returns a seq where x is the first element, and seq is the
rest? Which means that cons returns the same (constantly x) for which
(rest (constantly x)) could be said to equal (constantly x), as a
infinite string of x's is the same as an infinite string of x's one
shorter.

Although Clojure will take an infinite amount of time to test this for
you.




>
> At the moment I'm leaning toward DITA for heavy-duty documentation, in part
> because it would allow generation of manpages.  You can see an example at
> leiningen-doc <https://github.com/mobileink/leiningen-doc> - pdf output
> examples are in doc/pdf.  It's mostly an outline at the moment, but if you
> look at the driver file
> ugbook.ditamap<https://github.com/mobileink/leiningen-doc/blob/master/ugbook.ditamap>and
> the files in the ug directory you can get a quick idea of how it
> works.  Once you get the hang of it you can quickly write doco in a
> language specifically designed for tech documentation (and extend it if you
> wish).
>
> That puts me in a small (infinitesimal?) minority, I reckon, but DITA is
> evolving and growing, at least among professional tech writers.  An obvious
> research topic is how Clojure and DITA might be made to play nice together.

I was never a great fan of writing XML by hand, to be honest (which is
what this appears to be). The first example that I looked at:

https://github.com/mobileink/leiningen-doc/blob/master/ug/classpath.dita

incidentally, appears to be ill-formed, having two "</concept>" tags.
XML is hard to write.


>> > If it were genuinely failing us in some important way, it would be
>> > changed.
>>
>> This is, I think, a variant of the no true Scotsman fallacy. You can
>> say, about any complaint about documentation system are wrong, because
>> if they were right, it would be changed. By definition I can produce no
>> counter examples.
>>
>
> Does that mean I win?  ;)

Yes, but only if you can prove that you are a true Scotsman.



> Actually I was thinking in terms of evolution rather than definition.
> Since version 1 of clojure lots of unmet needs have been identified and
> then met; the language has evolved in response to genuine needs (meaning:
> new stuff is actually used to do useful things).  Since that hasn't
> happened much (to my knowledge) with respect to doc features, I conclude
> that those features are at least minimally sufficient ("optimal" was a bad
> choice of words) to contribute to "survival".  I'm pretty sure Rich Hickey
> would reject any proposed changes to the language that did not meet a
> genuine unmet need, and the Clojure community is sufficiently active and
> competent and imaginative, that I'm strongly inclined to believe that, were
> the doc features genuinely deficient or inadequate in some way, the
> language would have evolved in some way to remedy the problem.


Many features added to Clojure come from other languages -- consider the
requirement (or otherwise) for keyword arguments. People feel the lack
of these features early on, when they try and port other code (or just
their mind) to a new language.

Documentation is about scalability; it only hits when you have a
reasonable amount of code (especially external libraries). It also hits
newcomers most.

So, perhaps, the time is now.

Phil

-- 
You received this message because you are subscribed to the Google
Groups "Clojure" group.
To post to this group, send email to clojure@googlegroups.com
Note that posts from new members are moderated - please be patient with your 
first post.
To unsubscribe from this group, send email to
clojure+unsubscr...@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/clojure?hl=en
--- 
You received this message because you are subscribed to the Google Groups 
"Clojure" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to clojure+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Reply via email to