Merge with git+ssh://pasky.or.cz/srv/git/elinks.git

doc/Makefile

@@ -3,60 +3,24 @@ 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)"
+docdir = $(datadir)/doc
 
-# TODO: perl.pod should be pod2ized during make install. --pasky
+# Used by install-doc
+HTML_DIR = $(DESTDIR)$(docdir)/$(PACKAGE)/html
+PDF_DIR  = $(DESTDIR)$(docdir)/$(PACKAGE)/pdf
 
-### Script Dependencies
+#############################################################################
-#
+# Build files
-
-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
 
 TXT_DOCS = \
- bookmarks.txt \
+ features.txt \
- ecmascript.txt \
+ keymap-actions.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 \
  keymap-defaults.txt \
- keymap-actions.txt
+ option-command.txt \
-
+ option-config.txt
-TXT_DOCS += $(GEN_TXT_DOCS)
 
 HTML_DOCS-$(CONFIG_ASCIIDOC) += \
  elinks.1.html \
@@ -77,20 +41,97 @@ MAN_DOCS-$(CONFIG_XMLTO) += \
  elinks.conf.5 \
  elinkskeys.5
 
-
+# Use jw for generating PDF, since xmlto seems to freak out.
-# Only jw is used for generating PDF.
 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
+
+install-doc: all-docs update-man 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
+	$(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
+
+# 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
+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
+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 = $(LOCALES) $(CONF2DOC) > $@
+
+quiet_cmd_keys2doc = ' [$(LINK_COLOR)KEYS2DOC$(END_COLOR)]   $(RELPATH)$@'
+      cmd_keys2doc = $(LOCALES) $(KEYS2DOC) $(KBDBIND) $@ > $@
+
+features.txt: $(FEATURES) $(CONF2DOC)
+	$(call cmd,conf2doc)
+
+keymap-%.txt: $(KBDBIND) $(KEYS2DOC)
+	$(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 +139,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)))))
 
-
+api: $(patsubst %.txt,%.html,$(API_TXT))
-## 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) $@ > $@
 
 
-import-features.conf.txt: $(FEATURES) $(IMPORT_FEATURES_CONF)
+#############################################################################
-	$(IMPORT_FEATURES_CONF) > $@
+# Build commands and macros
-
-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) $<
 
       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 +203,5 @@ man_hack = sed "s/^\(\.TH \"ELINKS[^\"]*\" [0-9] \).*/\1\"$(1)\" \"$(MAN_DATE)\"
 perl-%.html: %.pl
 	$(call cmd,pod2html)
 
+
 include $(top_srcdir)/Makefile.lib

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
 ------------

doc/installation.txt

@@ -71,6 +71,6 @@ include::small.txt[]
 
 include::ecmascript.txt[]
 
-include::import-features.conf.txt[]
+include::features.txt[]
 
 endif::installation-webpage[]

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*{/) {

doc/tools/keys2doc

@@ -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__
+print_keymap_doc=
-MAIN ACTIONS
-~~~~~~~~~~~~
 
-$(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_doc main
-~~~~~~~~~~~~
+$print_keymap_doc edit
-
+$print_keymap_doc menu
-$(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__