From d282bc462578a6e47747c78d2d42883530f0d11e Mon Sep 17 00:00:00 2001 From: Mark Griffiths Date: Fri, 1 Aug 2014 03:37:32 +0100 Subject: Documentation update Rework for Doxygen >1.8. Moved large parts of the documentation to a simplified format, making use of Markdown enhancements and fixing bad long options. --- Makefile.in | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 78 insertions(+), 4 deletions(-) (limited to 'Makefile.in') diff --git a/Makefile.in b/Makefile.in index 4995dddc..c8467092 100644 --- a/Makefile.in +++ b/Makefile.in @@ -148,6 +148,11 @@ HDR_FILES := $(HDR_FILES_SRC:.hdr.in=.hdr) HELP_SRC := $(wildcard doc_src/*.txt) +# +# HTML includes needed for HTML help +# + +HTML_SRC := doc_src/user_doc.header.html doc_src/user_doc.footer.html doc_src/user_doc.css # # Files in the test directory @@ -252,11 +257,20 @@ prof: all # Depend on the sources (*.hdr.in) and manually make the # intermediate *.hdr and doc.h files if needed # The sed command deletes everything including and after the first -, for simpler version numbers +# Cleans up the user_doc/html directory once Doxygen is done. -user_doc: $(HDR_FILES_SRC) Doxyfile.user user_doc.head.html $(HELP_SRC) doc.h $(HDR_FILES) - (cat Doxyfile.user ; echo PROJECT_NUMBER=$(FISH_BUILD_VERSION) | sed "s/-.*//") | doxygen - && touch user_doc - +user_doc: $(HDR_FILES_SRC) Doxyfile.user $(HTML_SRC) $(HELP_SRC) doc.h $(HDR_FILES) doc_src/fish_lexicon_filter + (cat Doxyfile.user; echo INPUT_FILTER=doc_src/fish_lexicon_filter; \ + echo PROJECT_NUMBER=$(FISH_BUILD_VERSION) | sed "s/-.*//") | doxygen - && touch user_doc; \ + cd user_doc/html; rm -f bc_s.png bdwn.png closed.png ftv2*.png nav*.png open.png sync_*.png tab*.* doxygen.* dynsections.js jquery.js pages.html +# +# Build the help CSS files, using fish_lexicon_filter +# +doc_src/user_doc.css: doc_src/user_doc.css.in doc_src/fish_lexicon_filter + -rm $@ + cd doc_src; \ + cat user_doc.css.in >> user_doc.css # # Source code documentation. Also includes user documentation. @@ -328,11 +342,70 @@ toc.txt: $(HDR_FILES:index.hdr=index.hdr.in) doc_src/index.hdr: toc.txt doc_src/index.hdr.in cat $@.in | awk '{if ($$0 ~ /@toc@/){ system("cat toc.txt");} else{ print $$0;}}' >$@ +# +# To enable the lexicon filter, we first need to be aware of what fish +# considers to be a command, function, or external binary. We use +# command_list_toc.txt for the base commands. Scan the share/functions +# directory for other functions, some of which are mentioned in the docs, and +# use /share/completions to find a good selection of binaries. Additionally, +# colour defaults from __fish_config_interactive to set the docs colours when +# used in a 'cli' style context. +# + +lexicon.txt: doc_src/commands.hdr $(FUNCTIONS_DIR_FILES) $(COMPLETIONS_DIR_FILES) share/functions/__fish_config_interactive.fish + -rm lexicon.tmp lexicon_catalog.tmp lexicon_catalog.txt $@ + # Scan sources for commands/functions/binaries/colours. If GNU sed was portable, this could be much smarter. + sed >lexicon.tmp -n \ + -e "s|^.*>\([a-z][a-z_]*\)|'\1'|w lexicon_catalog.tmp" \ + -e "s|'\(.*\)'|cmnd \1|p"; mv lexicon_catalog.tmp lexicon_catalog.txt; \ + printf "%s\n" $(COMPLETIONS_DIR_FILES) | sed -n \ + -e "s|[^ ]*/\([a-z][a-z_-]*\).fish|'\1'|p" | fgrep -vx -f lexicon_catalog.txt | sed >>lexicon.tmp -n \ + -e 'w lexicon_catalog.tmp' \ + -e "s|'\(.*\)'|sbin \1|p"; cat lexicon_catalog.tmp >> lexicon_catalog.txt; \ + printf "%s\n" $(FUNCTIONS_DIR_FILES) | sed -n \ + -e "s|[^ ]*/\([a-z][a-z_-]*\).fish|'\1'|p" | fgrep -vx -f lexicon_catalog.txt | sed >>lexicon.tmp -n \ + -e 'w lexicon_catalog.tmp' \ + -e "s|'\(.*\)'|func \1|p"; \ + sed >lexicon.tmp -n \ + -e '/set_default/s/.*\(fish_[a-z][a-z_]*\).*$$/clrv \1/p' \ + -e '$$G;s/.*\n/==end==/p'; \ + sed >lexicon.tmp -n \ + -e '1G;s/.*\n/==styles==/p' \ + -e '/set_default/s/.*fish_color\(_[a-z][a-z_]*\)/style\1/' \ + -e '/^style_/s/_\([^ ]*\) --\([^ ]*\).*$$/ \1 \2/p' \ + -e '/^style_/s/_\([^ ]* [^- ]*\) --\([^ ]*\).*$$/ \1 \2/p' \ + -e '/^style_/s/_\([^ ]* [^- ]*\).*$$/ \1/p'; \ + mv lexicon.tmp lexicon.txt; rm -f lexicon_catalog.tmp lexicon_catalog.txt; + +# +# Compile Doxygen Input Filter from the lexicon. This is an executable sed +# script as Doxygen opens it via popen()(3) Input (doc.h) is piped through and +# matching words inside /fish../endfish blocks are marked up, contextually, +# with custom Doxygen commands in the form of @word_type{content}. These are +# trapped by ALIASES in the various Doxyfiles, allowing the content to be +# transformed depending on output type (HTML, man page, developer docs). In +# HTML, a style context can be applied through the /fish{style} block and +# providing suitable CSS in user_doc.css.in +# + +doc_src/fish_lexicon_filter: lexicon.txt doc_src/fish_lexicon_filter.in + -rm $@.tmp $@ + # Clean the filter input comments and set the shebang as sed can reside in + # /bin or /usr/bin and some versions dont allow more than one comment!. + sed <$@.in >$@.tmp -e 's|@sed@|'"`command -v sed`"'|' -e '/^[ ]*#[^!]/d' + # Scan through the lexicon, transforming each line to something usefue to Doxygen. + sed >$@.tmp -n \ + -e 's|^\([a-z][a-z][a-z][a-z]\) \([a-z_-]*\)$$|s,[[:<:]]\2[[:>:]],@\1{\2},g|p' \ + -e '/==end==/G;s/.*\n/b tidy/p' \ + -e '/==styles==/G;s/.*\n/:styles/p' \ + -e 's|^\(style [^ ]*\) \(.*\)$$|s,\1,\2,|p' \ + -e '$$G;s/.*\n/b processstyle/p'; \ + mv $@.tmp $@; if test -x $@; then true; else chmod a+x $@; fi # # doc.h is a compilation of the various snipptes of text used both for # the user documentation and for internal help functions into a single -# file that can be parsed dy Doxygen to generate the user +# file that can be parsed by Doxygen to generate the user # documentation. # @@ -748,6 +821,7 @@ clean: rm -f $(PROGRAMS) fish_tests key_reader rm -f command_list.txt command_list_toc.txt toc.txt rm -f doc_src/index.hdr doc_src/commands.hdr + rm -f doc_src/fish_lexicon_filter lexicon.txt doc_src/user_doc.css rm -f FISH-BUILD-VERSION-FILE if test "$(HAVE_DOXYGEN)" = 1; then \ rm -rf doc user_doc share/man; \ -- cgit v1.2.3