search

didierverna / declt

Reference manual generator for Common Lisp libraries
Other
38 stars 6 forks source link

Why there is no way to use Texinfo markup in docstrings? #10

Closed svetlyak40wt closed 3 years ago

didierverna commented 3 years ago

Several answers:

  1. quick'n dirty hack: currently, you can probably achieve that simply changing the definition of RENDER-DOCSTRING to something like this (untested): 
    (defun render-docstring (item) (when-let (docstring (docstring item)) (princ docstring)))
  2. you probably don't want to do that. Texinfo is not really a human-readable format and if you want your docstrings to remain readable as-is you want another kind of markup. In particular, I guess you're thinking cross-references within docstrings, in which case just look at the face of the Texinfo anchors in the generated .texi and you'll see what I mean ;-)
  3. I'm currently working on a more general improvement: the ability to equip Declt with different rendering engines (not only Texinfo), and the ability to specify different markup syntax in docstrings and other textual parts (I consider these two issues to be actually orthogonal). This is not ready yet because it require an extensive rewrite of many parts of Declt, but it's on the way...
svetlyak40wt commented 3 years ago

Thank you for the answer, @didierverna!

No problem! I just investigated Declt to write a template project for my CL Documentation Builders list. I thought there is something I missed.

BTW, some CL doc systems automatically cross-reference uppercased symbols found in docstrings!