Re: [Sbcl-devel] SB-MANUAL contrib prototype

[Gábor M. <me...@re...>]

I improved a couple of things and updated the samples.

- sb-manual: fix CONVERT-DOCSTRING-PACKAGE-OVERRIDES-TO-PAX

- sb-manual: add support for [label](uri) and [label][id]

- sb-manual: automatically USE-PAX
    
    Put a magic marker on the value of the variable holding the dummy
    section. Variables with these markers are recognized by PAX (from
    v0.4.12) as lazy sections. So, (DREF @FAKE 'SECTION) works. Then,
    whenever such a reference is RESOLVEd, the function following the
    magic marker is called. That function is USE-PAX in this case.
    
    The net effect of this hack is that PAX:DOCUMENTing a fake section
    will unfake it.
    
    Export USE-PAX for the remaining cases.

- sb-manual: USE-PAX automatically if PAX is already loaded
    
    ... when sb-manual is loaded.
    
    SWITCH-TO-PAX was renamed to USE-PAX.

- doc: fix overlapping section numbers and title in the PDF toc

- sb-manual: make GENERATE-TEXINFO unaffected by SWITCH-TO-PAX

- Add support for (DOCUMENTATION ... 'declaration)
    
    - Add docstrings for user-facing declaration.
    
    - Fix the hacks for declarations in the manual.
    
    - Add documentation of DOCUMENTATION extensions to the manual.
    
    - Add a "Declaration Index" appendix to the manual.

Gábor Melis <me...@re...> writes:

> Alright.
>
> The latest code and documentation are at
> https://github.com/melisgl/sbcl/commits/pax-doc/.
>
> The interesting commit is "PAXlike docs". The rest are bug fixes, and
> three large commits with docstring updates, lisp files with manual
> sections, and generated texinfo files.
>
> The following files were generated using the new Markdown-to-Texinfo
> converter, and subsequently compiled with Texinfo.
>
> https://quotenil.com/blog-files/sbcl-pax-doc/texinfo/sbcl.html
> https://quotenil.com/blog-files/sbcl-pax-doc/texinfo/sbcl.info
> https://quotenil.com/blog-files/sbcl-pax-doc/texinfo/sbcl.info-1
> https://quotenil.com/blog-files/sbcl-pax-doc/texinfo/sbcl.info-2
> https://quotenil.com/blog-files/sbcl-pax-doc/texinfo/sbcl.info-3
> https://quotenil.com/blog-files/sbcl-pax-doc/texinfo/sbcl.pdf
>
> The above are quite close to the current documentation (e.g.
> https://www.sbcl.org/manual/), but lots of small fixes have been made to
> the docstrings as well.
>
> The following alternatives were generated with PAX, with the command line
>
>     ./contrib/sb-manual/make-pax-docs.sh https://github.com/melisgl/sbcl
>
> https://quotenil.com/blog-files/sbcl-pax-doc/sbcl-manual.txt
> https://quotenil.com/blog-files/sbcl-pax-doc/sbcl-manual.md
> https://quotenil.com/blog-files/sbcl-pax-doc/sbcl-manual.pdf
> https://quotenil.com/blog-files/sbcl-pax-doc/html/sbcl-manual.html
>
> The main feature in these files (well, except the txt one) is linking:
> - cross-linking within the document,
> - linking to the CLHS, and
> - linking the locative (e.g. "[function]") to the sources on GitHub.
>
> SBCL, PAX, DRef, 3BMD and Slime required a couple of fixes. They are all
> available on GitHub (except https://github.com/3b/3bmd/pull/74), and
> hopefully in Ultralisp by now.
>
> For more information, see
>
> - the SB-MANUAL documentation
>
>     https://quotenil.com/blog-files/sbcl-pax-doc/html/sbcl-manual.html#x-28SB-MANUAL-3A-40SB-MANUAL-20MGL-PAX-3ASECTION-29
>
> - the docstring style guide:
>
>     https://github.com/melisgl/sbcl/blob/pax-doc/contrib/sb-manual/README.md
>
> - and the TODO list:
>
>    https://github.com/melisgl/sbcl/blob/pax-doc/contrib/sb-manual/TODO.md
>
> To avoid merge conflicts, I'll probably commit this soon if there are no
> objections, and then take my time with the TODO list.
>
> Cheers,
> Gábor