mirror of
git://git.code.sf.net/p/sbcl/sbcl
synced 2026-09-10 07:26:40 -04:00
4271a2f375
Summary
-------
Implement of a subset of PAX so that we can write PAX:DEFSECTIONlike
forms that supports the same restricted Markdown that we use for
docstrings and generate doc/manual/*.texinfo files from them.
Without PAX
-----------
There is no hard dependency on PAX. When the new SB-MANUAL contrib is
loaded, one can M-. around in documentation (sections are variables),
and function docstrings can now link to sections.
The generated Texinfo files are quite close to the originals, with
some loss of "semantic" markup: e.g. Markdown has `FOO` but no
@var{FOO} and @code{FOO}. We didn't derive much practical benefit from
that distinction.
With PAX
--------
(SB-MANUAL::SWITCH-TO-PAX) ensures that PAX is loaded and patches things
up, as if everything had been defined with PAX to begin with. Now, we
get PAX::@BROWSING-LIVE-DOCUMENTATION for low-latency, interactive
documentation work and PAX::@GENERATING-DOCUMENTATION for auto-linked
documentation.
Notable features:
- auto-generated links within the manual: if SB-EXT:EXIT is mentioned,
then it's linked to its documentation.
- auto-generated links to the CLHS (these links are red in PDF)
- locatives (e.g. the "[function]" in "- [function] SB-EXT:EXIT" are
also links and they go to the sources on GitHub (in live browsing,
they tell Slime to open the definition)
Details
-------
- Factor out the Markdown-to-Texinfo code into a new SB-MANUAL
contrib.
- Convert doc/manual/*.texinfo files to PAXlike DEFSECTION format and
add each chapter as a contrib/sb-manual/doc/<chapter>.lisp file.
- Fix a *lot* of small issues during the conversion.
- Make doc/make-doc.sh regenerate the all .texinfo files except
sbcl.texinfo and backmatter.texinfo.
- Fix docstrings of Lisp definitions used in the manual to conform to
the supported Markdown syntax.
- Retain the Texinfo function, variable and type indicies but drop the
concept index. There is no obvious way to support that in Markdown,
and it was used rather sporadically rather incomplete.
- Even with the new features, the amount of Lisp code didn't change
significantly.
- See contrib/sb-manual/README for the Todo list
107 lines
2.6 KiB
Makefile
107 lines
2.6 KiB
Makefile
SBCLTEXI:=sbcl.texinfo
|
|
ASDFTEXI:=asdf.texinfo
|
|
# The rest of the texinfo files are generated.
|
|
DOCFILES:=sbcl.texinfo backmatter.texinfo $(ASDFTEXI)
|
|
TMPTYPES:=aux cp cps fn fns ky log pg toc tp tps vr vrs
|
|
TMPFILES:=$(foreach target,asdf sbcl,$(foreach type,$(TMPTYPES),$(target).$(type)))
|
|
PSFILES=sbcl.ps asdf.ps
|
|
PDFFILES=sbcl.pdf asdf.pdf
|
|
INFOFILES=sbcl.info asdf.info
|
|
HTMLDIRS=$(basename $(SBCLTEXI)) $(basename $(ASDFTEXI))
|
|
HTMLFILES=sbcl.html asdf.html
|
|
CONTRIB_SRC_DIR="../../contrib/"
|
|
I_FLAGS=-I $(CONTRIB_SRC_DIR)
|
|
|
|
# SBCL_SYSTEM is an optional argument to this make program. If this
|
|
# variable is set, its contents are used as the command line for
|
|
# invoking SBCL.
|
|
|
|
# When passing a non-standard SBCL_SYSTEM, be sure to set the
|
|
# environment variable SBCL_HOME to a useful value, as well.
|
|
|
|
ifeq ($(MAKEINFO),)
|
|
MAKEINFO:=makeinfo
|
|
endif
|
|
|
|
ifeq ($(TEXI2PDF),)
|
|
TEXI2PDF:=texi2dvi -p
|
|
endif
|
|
|
|
ifeq ($(DVIPS),)
|
|
DVIPS:=dvips
|
|
endif
|
|
|
|
.PHONY: all
|
|
all: $(ASDFTEXI) ps pdf info html
|
|
|
|
.PHONY: dist
|
|
dist: html pdf
|
|
|
|
asdf.texinfo:
|
|
rm -f asdf.texinfo
|
|
ln -s ../../contrib/asdf/asdf.texinfo
|
|
|
|
version.texinfo:
|
|
rm -f version.texinfo
|
|
ln -s ../../contrib/asdf/version.texinfo
|
|
|
|
# html documentation; output in $(HTMLDIRS)
|
|
.PHONY: html
|
|
html: html-stamp
|
|
|
|
html-stamp: $(DOCFILES) generated-texinfo-files
|
|
@rm -rf $(HTMLDIRS)
|
|
@rm -f $(HTMLFILES)
|
|
# $(MAKEINFO) $(I_FLAGS) --html --css-include=style-multi.css $(SBCLTEXI)
|
|
# $(MAKEINFO) --html --css-include=style-multi.css $(ASDFTEXI)
|
|
$(MAKEINFO) $(I_FLAGS) --html --no-split --css-include=style-common.css --css-include=style-single.css $(SBCLTEXI)
|
|
$(MAKEINFO) --html --no-split --css-include=style-common.css --css-include=style-single.css $(ASDFTEXI)
|
|
touch html-stamp
|
|
|
|
# Postscript documentation
|
|
.PHONY: ps
|
|
ps: $(PSFILES)
|
|
|
|
%.ps: %.dvi
|
|
dvips -q -o $@ $<
|
|
|
|
# DVI generation
|
|
%.dvi: %.texinfo $(DOCFILES) generated-texinfo-files
|
|
texi2dvi -q $(I_FLAGS) $<
|
|
|
|
# PDF documentation
|
|
.PHONY: pdf
|
|
pdf: $(PDFFILES)
|
|
|
|
%.pdf: %.texinfo $(DOCFILES) generated-texinfo-files
|
|
$(TEXI2PDF) -q $(I_FLAGS) $<
|
|
|
|
# info docfiles
|
|
.PHONY: info
|
|
info: $(INFOFILES)
|
|
|
|
%.info: %.texinfo $(DOCFILES) generated-texinfo-files
|
|
$(MAKEINFO) $(I_FLAGS) $<
|
|
|
|
# Texinfo docstring snippets
|
|
generated-texinfo-files: generated-texinfo-stamp
|
|
sh generate-texinfo.sh "$(SBCL_SYSTEM)"
|
|
|
|
generated-texinfo-stamp:
|
|
touch generated-texinfo-stamp
|
|
|
|
.PHONY: clean
|
|
clean:
|
|
rm -f *~ *.bak *.orig \#*\# .\#* texput.log *.fasl
|
|
rm -rf $(HTMLDIRS)
|
|
rm -f $(HTMLFILES)
|
|
rm -f contrib-docs.texi-temp
|
|
rm -f package-locks.texi-temp
|
|
rm -f variables.texinfo
|
|
rm -f $(PSFILES) $(PDFFILES) html-stamp generated-texinfo-stamp
|
|
rm -f $(TMPFILES) $(INDEXFILES)
|
|
rm -f sbcl.info sbcl.info-* asdf.info
|
|
|
|
.PHONY: distclean
|
|
distclean: clean
|