From bcdd3fafca0f71d32204e31f3689e2ba86c33d23 Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Fri, 13 Jan 2006 12:02:26 +0100 Subject: [PATCH 1/7] Output only to stdout instead of creating files directly --- doc/tools/make-elinkskeys-manpage | 53 ++++++++++++------------------- 1 file changed, 21 insertions(+), 32 deletions(-) diff --git a/doc/tools/make-elinkskeys-manpage b/doc/tools/make-elinkskeys-manpage index 5f45bb74d..e4b537e83 100755 --- a/doc/tools/make-elinkskeys-manpage +++ b/doc/tools/make-elinkskeys-manpage @@ -16,12 +16,22 @@ KBDBIND=$1 CONFIGDIR=$(dirname "$KBDBIND") +OUTPUT=$2 test -d "$CONFIGDIR" || exit +print_title() +{ + echo "$1" | tr 'a-z' 'A-Z' + echo "$1" | sed 's/[^~]/~/g' + echo +} + print_keymap_actions() { - keymap=$1 + keymap="$1" + + print_title "$keymap ACTIONS" echo 'ifdef::backend-xhtml11[]' echo '`----------------------------------`----------------------------------------------------------------------------' @@ -59,6 +69,8 @@ print_keymap_defaults() keymap="$1" KEYMAP=$(echo $1 | tr '[a-z]' '[A-Z]') + print_title "$keymap KEYS" + echo 'ifdef::backend-xhtml11[]' echo '`-----------`-------------------------------------------------------------------------------' echo 'Key Description (Action)' @@ -113,36 +125,13 @@ print_keymap_defaults() } -cat > keymap-actions.txt << __END__ -MAIN ACTIONS -~~~~~~~~~~~~ +print_keymap_doc= -$(print_keymap_actions main) +case "$OUTPUT" in + *default*) print_keymap_doc="print_keymap_defaults" ;; + *action*) print_keymap_doc="print_keymap_actions" ;; +esac -EDIT ACTIONS -~~~~~~~~~~~~ - -$(print_keymap_actions edit) - -MENU ACTIONS -~~~~~~~~~~~~ - -$(print_keymap_actions menu) -__END__ - -cat > keymap-defaults.txt << __END__ -MAIN KEYS -~~~~~~~~~ - -$(print_keymap_defaults main) - -EDIT KEYS -~~~~~~~~~ - -$(print_keymap_defaults edit) - -MENU KEYS -~~~~~~~~~ - -$(print_keymap_defaults menu) -__END__ +$print_keymap_doc main +$print_keymap_doc edit +$print_keymap_doc menu From 63f4a15d91c22a813d58c1b9a42dae19ee01f349 Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Fri, 13 Jan 2006 12:14:05 +0100 Subject: [PATCH 2/7] Add ending punctuation for one-liners; fix missing ending ';' --- doc/tools/code2doc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/tools/code2doc b/doc/tools/code2doc index 979c8f193..6513ffe71 100755 --- a/doc/tools/code2doc +++ b/doc/tools/code2doc @@ -38,9 +38,9 @@ while (<>) { my $end = s/\s*\*+\//\n/ ? 'yes' : undef; - if ($end and /[^=]*[\s*](\w+)[\s:,;].*\/\*:\s*(.*)/) { + if ($end and /[^=]*[\s*](\w+)[\s:,;].*\/\*:\s*(.*)([.]\s*)?$/) { # Implicit id for enum values and struct members. - print "\nid:[$idpath$1]::\n\t$2\n"; + print "\nid:[$idpath$1]::\n\t$2.\n"; } elsif ($inblock) { # Redo the indentation, preserve empty lines. @@ -65,7 +65,7 @@ while (<>) while (not /(struct|enum|typedef|[^=])*[\s*](\w+).*[\[:,;{]/) { my $line = $_; $_ .= <>; - last if $_ eq $line + last if $_ eq $line; } if (/struct\s+(\w+)\s*{/) { From 75bf42bfe04690de550a4bcedefe6f1b09d1b0b5 Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Fri, 13 Jan 2006 12:17:03 +0100 Subject: [PATCH 3/7] Simplify further; only list generated files; move things around; comment --- doc/Makefile | 206 ++++++++++++++++++++----------------------- doc/installation.txt | 2 +- 2 files changed, 99 insertions(+), 109 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 631d5687c..43b164554 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -3,60 +3,18 @@ include $(top_builddir)/Makefile.config SUBDIRS = man +# A little trick to simplify some of the rules. VPATH = $(builddir):$(srcdir):$(top_srcdir)/contrib/perl -#export PATH="tools:$(PATH)" - -# TODO: perl.pod should be pod2ized during make install. --pasky - -### Script Dependencies -# - -ELINKS = $(top_builddir)/src/elinks -FEATURES = $(top_srcdir)/features.conf -KBDBIND = $(top_srcdir)/src/config/kbdbind.c - - -### Locale env vars to override system one to ensure commands -# using elinks binary will generate texts in english -# -LOCALES = LC_ALL=C LANGUAGE=en - -### Scripts -# - -CODE2DOC = $(top_srcdir)/doc/tools/code2doc -HELP2DOC = $(top_srcdir)/doc/tools/help2doc -IMPORT_FEATURES_CONF = $(top_srcdir)/doc/tools/import-features.conf +############################################################################# +# Build files TXT_DOCS = \ - bookmarks.txt \ - ecmascript.txt \ - elinks.1.txt \ - elinkskeys.5.txt \ - exmode.txt \ - faq.txt \ - installation.txt \ - introduction.txt \ - lua-scripting.txt \ - mailcap.txt \ - manual.txt \ - marks.txt \ - mime.txt \ - remote.txt \ - small.txt \ - tabs.txt \ - terminals.txt \ - urlshortcuts.txt - -GEN_TXT_DOCS = \ - import-features.conf.txt \ - option-command.txt \ - option-config.txt \ + features.txt \ + keymap-actions.txt \ keymap-defaults.txt \ - keymap-actions.txt - -TXT_DOCS += $(GEN_TXT_DOCS) + option-command.txt \ + option-config.txt HTML_DOCS-$(CONFIG_ASCIIDOC) += \ elinks.1.html \ @@ -77,20 +35,83 @@ MAN_DOCS-$(CONFIG_XMLTO) += \ elinks.conf.5 \ elinkskeys.5 - -# Only jw is used for generating PDF. +# Use jw for generating PDF, since xmlto seems to freak out. PDF_DOCS-$(CONFIG_JW) += \ manual.pdf -## API Docs -# -ifneq ($(findstring api,$(MAKECMDGOALS)),) +############################################################################# +## Set the default doc rules + +MAN_DOCS = $(MAN_DOCS-yes) +HTML_DOCS = $(HTML_DOCS-yes) +PDF_DOCS = $(PDF_DOCS-yes) + +txt: $(TXT_DOCS) +html: txt $(HTML_DOCS) +pdf: txt $(PDF_DOCS) +man: txt $(MAN_DOCS) + +all-docs: man html pdf + +update-man: man + $(call cmd,installdata,elinks.1,man/man1/elinks.1.in) + $(call cmd,installdata,elinkskeys.5,man/man5/) + $(call cmd,installdata,elinks.conf.5,man/man5/) + +clean-local: + @$(RM) -r api $(TXT_DOCS) $(MAN_DOCS) $(HTML_DOCS) $(PDF_DOCS) *.tmp *.xml + +# TODO: perl.pod should be pod2ized during make install. --pasky +install-local: + + +############################################################################# +# Generated asciidoc files + +# Scripts and Dependencies +CODE2DOC = $(srcdir)tools/code2doc +HELP2DOC = $(srcdir)tools/help2doc +IMPORT_FEATURES_CONF = $(srcdir)tools/import-features.conf +MAKE_ELINKSKEYS_MANPAGE = $(srcdir)tools/make-elinkskeys-manpage +ELINKS = $(top_builddir)/src/elinks +FEATURES = $(top_srcdir)/features.conf +KBDBIND = $(top_srcdir)/src/config/kbdbind.c + +# Locale env vars to override system one to ensure commands +# using elinks binary will generate texts in english +LOCALES = LC_ALL=C LANGUAGE=en + +# FIXME: Keep generated .txt files relative to the source directory and files +# they are included in. +quiet_cmd_help2doc = ' [$(LINK_COLOR)HELP2DOC$(END_COLOR)] $(RELPATH)$@' + cmd_help2doc = $(LOCALES) $(HELP2DOC) $(ELINKS) $@ > $@ + +quiet_cmd_conf2doc = ' [$(LINK_COLOR)CONF2DOC$(END_COLOR)] $(RELPATH)$@' + cmd_conf2doc = $(IMPORT_FEATURES_CONF) > $@ + +quiet_cmd_keys2doc = ' [$(LINK_COLOR)KEYS2DOC$(END_COLOR)] $(RELPATH)$@' + cmd_keys2doc = $(LOCALES) $(MAKE_ELINKSKEYS_MANPAGE) $(KBDBIND) $@ > $@ + +features.txt: $(FEATURES) $(IMPORT_FEATURES_CONF) + $(call cmd,conf2doc) + +keymap-%.txt: $(MAKE_ELINKSKEYS_MANPAGE) $(KBDBIND) + $(call cmd,keys2doc) + +option-%.txt: $(ELINKS) $(HELP2DOC) + $(call cmd,help2doc) + + +# API Docs + +ifeq ($(findstring api,$(MAKECMDGOALS)),api) API = $(shell find $(top_srcdir)/src/ -name '*.h' -exec grep -q 'API Doc' \{\} \; -printf "%p " | sort) endif define api_doc -api/$(2).txt: $(1) +api/$(2).txt: $(1) $(CODE2DOC) + @test -d api || $(MKINSTALLDIRS) api @$(CODE2DOC) $(1) > $$@ API_TXT += api/$(2).txt endef @@ -98,81 +119,49 @@ endef api_name = $(shell sed -n 's/.*API Doc\s*::\s*\([^ ]*\).*/\1/p' < $(1)) $(foreach api,$(API),$(eval $(call api_doc,$(api),$(call api_name,$(api))))) - -## Se the default doc rules - -MAN_DOCS = elinks.conf.5 $(MAN_DOCS-yes) -HTML_DOCS = $(HTML_DOCS-yes) -PDF_DOCS = $(PDF_DOCS-yes) -API_DOCS = $(patsubst %.txt,%.html,$(API_TXT)) - -api-dir: - @test -d api || $(MKINSTALLDIRS) api - -txt: $(addprefix $(srcdir),$(TXT_DOCS)) -html: txt $(HTML_DOCS) -pdf: txt $(PDF_DOCS) -man: txt $(MAN_DOCS) -api: api-dir $(API_DOCS) - -all-docs: man html pdf - -update-man: man - $(call cmd,installdata,$(srcdir)elinks.1,man/man1/elinks.1.in) - $(call cmd,installdata,$(srcdir)elinkskeys.5,man/man5/) - $(call cmd,installdata,$(srcdir)elinks.conf.5,man/man5/) - -clean-local: - @$(RM) -r api $(GEN_TXT_DOCS) $(MAN_DOCS) $(HTML_DOCS) $(PDF_DOCS) *.tmp *.xml - -# Autogenerated files. - -# FIXME: Keep generated .txt files relative to the source directory and files -# they are included in. -quiet_cmd_help2doc = ' [$(LINK_COLOR)HELP2DOC$(END_COLOR)] $(RELPATH)$@' - cmd_help2doc = $(LOCALES) $(HELP2DOC) $(ELINKS) $@ > $@ +api: $(patsubst %.txt,%.html,$(API_TXT)) -import-features.conf.txt: $(FEATURES) $(IMPORT_FEATURES_CONF) - $(IMPORT_FEATURES_CONF) > $@ - -keymap-defaults.txt keymap-actions.txt: $(MAKE_ELINKSKEYS_MANPAGE) $(KBDBIND) - $(LOCALES) $(srcdir)tools/make-elinkskeys-manpage $(KBDBIND) - -option-%.txt: $(ELINKS) $(HELP2DOC) - $(call cmd,help2doc) - -## Default build rules -# - -quiet_cmd_asciidoc = ' [$(LINK_COLOR)ASCIIDOC$(END_COLOR)] $(RELPATH)$@' - cmd_asciidoc = $(ASCIIDOC) -f asciidoc.conf -b $(2) -d $(call doctype,$<) -o $@ $< - - quiet_cmd_xmlto = ' [$(LINK_COLOR)XMLTO$(END_COLOR)] $(RELPATH)$@' - cmd_xmlto = $(XMLTO) $(3) $(2) $< +############################################################################# +# Build commands and macros quiet_cmd_jw = ' [$(LINK_COLOR)JW$(END_COLOR)] $(RELPATH)$@' cmd_jw = $(JW) -b $(2) $< + quiet_cmd_xmlto = ' [$(LINK_COLOR)XMLTO$(END_COLOR)] $(RELPATH)$@' + cmd_xmlto = $(XMLTO) $(3) $(2) $< + quiet_cmd_pod2html = ' [$(LINK_COLOR)POD2HTML$(END_COLOR)] $(RELPATH)$@' cmd_pod2html = $(POD2HTML) --outfile=$@ < $< +quiet_cmd_asciidoc = ' [$(LINK_COLOR)ASCIIDOC$(END_COLOR)] $(RELPATH)$@' + cmd_asciidoc = $(ASCIIDOC) -f asciidoc.conf -b $(2) -d $(call doctype,$<) -o $@ $< + +# Based on filename in $(1) find out asciidoc doctype. doctype = $(if $(findstring .1.,$(1)),manpage,$(if $(findstring .5.,$(1)),manpage,book)) +# Loosely track dependencies via asciidoc includes. +asciidoc_dep = sed -n 's@include::\(.*\)\[.*@$@: \1@p' < $< > .deps/$(@F).asciidoc + +-include .deps/*.asciidoc + +# Do a little post-processing of man pages. Inserting title headers and date. MAN_DATE = $(shell date -I) man_desc = `sed -n 's/:Description:\s*\(.*\)/\1/p' < $(subst .xml,.txt,$<)` man_hack = sed "s/^\(\.TH \"ELINKS[^\"]*\" [0-9] \).*/\1\"$(1)\" \"$(MAN_DATE)\" \"$(1)\"/" < $@ | \ sed "s/@squote@/\\\\'/g" > $@.tmp && mv $@.tmp $@ --include .deps/* + +############################################################################# +# Build recipies %.html: %.txt asciidoc.conf $(call cmd,asciidoc,xhtml11) - @-sed -n 's#include::\(.*\)\[.*#$@: \1#p' < $< > .deps/$(@F) + $(call asciidoc_dep) %.xml: %.txt asciidoc.conf $(call cmd,asciidoc,docbook) - @-sed -n 's#include::\(.*\)\[.*#$@: \1#p' < $< > .deps/$(@F) + $(call asciidoc_dep) %.1: %.1.xml $(call cmd,xmlto,man) @@ -194,4 +183,5 @@ man_hack = sed "s/^\(\.TH \"ELINKS[^\"]*\" [0-9] \).*/\1\"$(1)\" \"$(MAN_DATE)\" perl-%.html: %.pl $(call cmd,pod2html) + include $(top_srcdir)/Makefile.lib diff --git a/doc/installation.txt b/doc/installation.txt index 87c96b286..c999f1607 100644 --- a/doc/installation.txt +++ b/doc/installation.txt @@ -71,6 +71,6 @@ include::small.txt[] include::ecmascript.txt[] -include::import-features.conf.txt[] +include::features.txt[] endif::installation-webpage[] From b8301917ec55e6999002864354a5f3ccc721bf6d Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Fri, 13 Jan 2006 12:42:14 +0100 Subject: [PATCH 4/7] Add install-doc rule --- doc/Makefile | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/doc/Makefile b/doc/Makefile index 43b164554..910575279 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -6,6 +6,12 @@ SUBDIRS = man # A little trick to simplify some of the rules. VPATH = $(builddir):$(srcdir):$(top_srcdir)/contrib/perl +docdir = $(datadir)/doc + +# Used by install-doc +HTML_DIR = $(DESTDIR)$(docdir)/$(PACKAGE)/html +PDF_DIR = $(DESTDIR)$(docdir)/$(PACKAGE)/pdf + ############################################################################# # Build files @@ -54,6 +60,19 @@ man: txt $(MAN_DOCS) all-docs: man html pdf +install-doc: all-docs install + $(foreach doc,$(HTML_DOCS), \ + if test -d $(doc); then \ + $(MKINSTALLDIRS) $(DESTDIR)$(docdir)/$(PACKAGE)/html/$(doc); \ + $(call ncmd,installdata,$(doc)/*,$(HTML_DIR)/$(doc)); \ + else \ + $(MKINSTALLDIRS) $(DESTDIR)$(docdir)/$(PACKAGE)/html; \ + $(call ncmd,installdata,$(doc),$(HTML_DIR)); \ + fi;) + $(foreach doc,$(PDF_DOCS), \ + $(MKINSTALLDIRS) $(DESTDIR)$(docdir)/$(PACKAGE)/pdf; \ + $(call ncmd,installdata,$(doc),$(PDF_DIR);)) + update-man: man $(call cmd,installdata,elinks.1,man/man1/elinks.1.in) $(call cmd,installdata,elinkskeys.5,man/man5/) From 54e980abe43e1636b1068dc722a83ff5d7e0a620 Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Fri, 13 Jan 2006 12:48:37 +0100 Subject: [PATCH 5/7] Make install-doc depend on update-man to get the newest --- doc/Makefile | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/Makefile b/doc/Makefile index 910575279..92f721aa2 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -60,7 +60,7 @@ man: txt $(MAN_DOCS) all-docs: man html pdf -install-doc: all-docs install +install-doc: all-docs update-man install $(foreach doc,$(HTML_DOCS), \ if test -d $(doc); then \ $(MKINSTALLDIRS) $(DESTDIR)$(docdir)/$(PACKAGE)/html/$(doc); \ @@ -74,9 +74,10 @@ install-doc: all-docs install $(call ncmd,installdata,$(doc),$(PDF_DIR);)) update-man: man - $(call cmd,installdata,elinks.1,man/man1/elinks.1.in) - $(call cmd,installdata,elinkskeys.5,man/man5/) - $(call cmd,installdata,elinks.conf.5,man/man5/) + $(if $(MAN_DOCS), \ + $(call ncmd,installdata,elinks.1,man/man1/elinks.1.in); \ + $(call ncmd,installdata,elinkskeys.5,man/man5/); \ + $(call ncmd,installdata,elinks.conf.5,man/man5/)) clean-local: @$(RM) -r api $(TXT_DOCS) $(MAN_DOCS) $(HTML_DOCS) $(PDF_DOCS) *.tmp *.xml From 57e7bafa83c2e60bb7a6aaa4b02f8e1262718a79 Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Fri, 13 Jan 2006 12:55:36 +0100 Subject: [PATCH 6/7] Shortly mention install-doc in the README --- doc/README | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/README b/doc/README index be56d7f9b..d47ae3759 100644 --- a/doc/README +++ b/doc/README @@ -99,6 +99,10 @@ Note: You do not need to build manpages. They are shipped with ELinks. Note: You must first build the ELinks binary for "make all-docs" to work successfully. The binary is used for getting option documentation. +The documentation can be installed with: + + $ make install-doc + Contributing ------------ From fabd3df9848ba6e8ac51a0acfe318f3f16a6318e Mon Sep 17 00:00:00 2001 From: Jonas Fonseca Date: Fri, 13 Jan 2006 12:58:47 +0100 Subject: [PATCH 7/7] mv import-features.conf conf2doc; mv make-elinkskeys-manpage keys2doc --- doc/Makefile | 22 +++++++++---------- doc/tools/{import-features.conf => conf2doc} | 0 .../{make-elinkskeys-manpage => keys2doc} | 0 3 files changed, 11 insertions(+), 11 deletions(-) rename doc/tools/{import-features.conf => conf2doc} (100%) rename doc/tools/{make-elinkskeys-manpage => keys2doc} (100%) diff --git a/doc/Makefile b/doc/Makefile index 92f721aa2..6e1cc6fe0 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -90,13 +90,13 @@ install-local: # Generated asciidoc files # Scripts and Dependencies -CODE2DOC = $(srcdir)tools/code2doc -HELP2DOC = $(srcdir)tools/help2doc -IMPORT_FEATURES_CONF = $(srcdir)tools/import-features.conf -MAKE_ELINKSKEYS_MANPAGE = $(srcdir)tools/make-elinkskeys-manpage -ELINKS = $(top_builddir)/src/elinks -FEATURES = $(top_srcdir)/features.conf -KBDBIND = $(top_srcdir)/src/config/kbdbind.c +CODE2DOC = $(srcdir)tools/code2doc +HELP2DOC = $(srcdir)tools/help2doc +CONF2DOC = $(srcdir)tools/conf2doc +KEYS2DOC = $(srcdir)tools/make-elinkskeys-manpage +ELINKS = $(top_builddir)/src/elinks +FEATURES = $(top_srcdir)/features.conf +KBDBIND = $(top_srcdir)/src/config/kbdbind.c # Locale env vars to override system one to ensure commands # using elinks binary will generate texts in english @@ -108,15 +108,15 @@ quiet_cmd_help2doc = ' [$(LINK_COLOR)HELP2DOC$(END_COLOR)] $(RELPATH)$@' cmd_help2doc = $(LOCALES) $(HELP2DOC) $(ELINKS) $@ > $@ quiet_cmd_conf2doc = ' [$(LINK_COLOR)CONF2DOC$(END_COLOR)] $(RELPATH)$@' - cmd_conf2doc = $(IMPORT_FEATURES_CONF) > $@ + cmd_conf2doc = $(LOCALES) $(CONF2DOC) > $@ quiet_cmd_keys2doc = ' [$(LINK_COLOR)KEYS2DOC$(END_COLOR)] $(RELPATH)$@' - cmd_keys2doc = $(LOCALES) $(MAKE_ELINKSKEYS_MANPAGE) $(KBDBIND) $@ > $@ + cmd_keys2doc = $(LOCALES) $(KEYS2DOC) $(KBDBIND) $@ > $@ -features.txt: $(FEATURES) $(IMPORT_FEATURES_CONF) +features.txt: $(FEATURES) $(CONF2DOC) $(call cmd,conf2doc) -keymap-%.txt: $(MAKE_ELINKSKEYS_MANPAGE) $(KBDBIND) +keymap-%.txt: $(KBDBIND) $(KEYS2DOC) $(call cmd,keys2doc) option-%.txt: $(ELINKS) $(HELP2DOC) diff --git a/doc/tools/import-features.conf b/doc/tools/conf2doc similarity index 100% rename from doc/tools/import-features.conf rename to doc/tools/conf2doc diff --git a/doc/tools/make-elinkskeys-manpage b/doc/tools/keys2doc similarity index 100% rename from doc/tools/make-elinkskeys-manpage rename to doc/tools/keys2doc