Oddities in generated documentation

[snunez1]

I've just pushed out some newly generated documentation, and there are a few things I'm not clear on. The HTML docs were generated with makeinfo, and the doc link is here: https://lisp-stat.github.io/array-operations/

1. The system title is repeated right at the top. I also see this behavior in the generated epub.
2. The documentation is listing quite a few systems for array-operations, when in fact there are only two. The main system and a test one. It appears to be listing the individual packages as systems.
3. In sections 2.2.1 onward, every filename is stated as file-type.lisp. This is not correct.

Questions:

1. Is it possible to preserve formatting within a documentation string? I have them nicely formatted in the code, but they get scrambled in the doc output.
2. Will markdown output be coming anytime soon? As far as markup languages, it's rather dull, but it seems to have become the de-facto standard. Being able to add markdown to the doc strings may be able to produce much richer output.
3. Is there a way to link to other functions? By convention, I capitalise all functions and wonder if we could have some kind of convention to signal a word or phrase should be linked to another point in the documentation.
4. Should doc strings have newlines, or is the recommendation for them to be single long strings and formatted by declt or texinfo?
5. How to I populate the 'Concepts' section?

[didierverna]

Hello,

I've started looking into this.

About the title, it seems to be an artefact of Texinfo's HTML generation. If you look at the manuals on the Quickref website, you'll see that they're all like this, but there is a global navbar behind the centered title. Presumably, the first is the document's title, and the second one is from Texinfo's "Top" node. I don't recall if the output was always like this, but I will check if something has changed in recent Texinfo, or if I can do something about it for HTML output.

As for the rest, Declt is coherent with what it actually finds, and the oddities seem to be related to the use of ASDF's package inferred system mechanism (which I don't really know). There /are/ indeed many ASDF systems in memory (one per package, indeed, as opposed to the only two in the source file). About the file names, I see many ASDF/LISP-ACTION:CL-SOURCE-FILE's with a correct absolute file name, but with "file-type" as their name, which then appears in the documentation.

I guess I need to have a look at this package-inferred-system thing...

[didierverna]

As for your questions.

1. (and 2 and 4) See section A.2 of the user manual. No control is available right now. At least Markdown and verbatim formatting will come... sometime in the future.
2. Not possible until docstrings are processed in some kind of markup, but it's on my TODO List.
3. You don't. Currently, the only way to do so is to use Texinfo's @cindex command in the introduction or conclusion section, because these are the only sections that can be provided as-is. Texinfo has had some interesting new features regarding indexes generation and I need to rethink that whole part of Declt...

[didierverna]

More investigation reveals that Texinfo 7 has fixed the duplicated title issue. For former versions (6.8 notably), maybe you can try calling makeinfo with --set-customization-variable NO_TOP_NODE_OUPUT=true.

[snunez1]

Just checking in here to see if there's anything ready to be merged into master. I was hoping I could help finish up some of the pending work, but I don't see any branches with activity.

Are there any tasks that someone can help with that don't require a huge learning curve? It would be especially useful if we could improve the HTML output -- if this is possible. May be a shorter route is to improve the chain from docs->texinfo->HTML via pandoc or some other converter?