As discussed; the attached patch is a draft of how this could work.
1) It was necessary to remove the subdirs below doc/. All sources
and generated files are now in doc/. This also makes it much
easier to generate and install files. Makefiles don't work well
if files are located in different diectories anyway.
2) The Makefile.am now uses the standard "man1_MANS" file type to
describe the generated files. That should make local installation
rules unnecessary. Not sure whether it also handles the
"transform" stuff or not. For now I've removed it.
3) There's a new, experimental page "fvwm3commands.adoc" which
has a header and then just includes the file
fvwm3_commands.section. This file is generated from fvwm3.adoc by
extracting all text between the two comments
// BEGIN 'commands'
...
// END 'commands'
Sections to extract are listed in the variable "EXTRACT_SECIONS".
For now, all man pages simply depend on all section files. To
build real dependencies we'd have to extract the include
directives from the .adoc files, but this seems to be overkill.
The split man page sources are very simple:
--snip--
= FVWM3COMMANDS(1)
== NAME
fvwm3commands - fvwm build-in commands
include::fvwm3_commands.section[]
--snip--
4) Also removed the "QUIET_ASCIIDOC" thing because it seems to be
pointless to suppress single-line rules in the output. (Don't
care much about it, though.)
5) fvwm3.1 still contains everything. I'd like to rename that to
fvwm3all.1 and then find a way to create fvwm3.1 without the
sections that have their own page, containing placeholders that
point to the other pages.
6) We want to add a footer that points to the related pages.
--
Seems to do what is intended; "make install" and "make uninstall"
work fine, but I haven't tried to build and test a distro from
that.
Comments?
Ciao
Dominik ^_^ ^_^
--
Dominik Vogt
From 3994b8a87ac7d2637215dd514d21634e490f0a29 Mon Sep 17 00:00:00 2001
From: Dominik Vogt <dominik.v...@gmx.de>
Date: Mon, 15 Nov 2021 16:52:38 +0100
Subject: [PATCH] DRAFT: Split main man page.
---
doc/.gitignore | 1 +
doc/{modules => }/FvwmAnimate.adoc | 0
doc/{modules => }/FvwmAuto.adoc | 0
doc/{modules => }/FvwmBacker.adoc | 0
doc/{modules => }/FvwmButtons.adoc | 0
doc/{bin => }/FvwmCommand.adoc | 0
doc/{modules => }/FvwmConsole.adoc | 0
doc/{modules => }/FvwmEvent.adoc | 0
doc/{modules => }/FvwmForm.adoc | 0
doc/{modules => }/FvwmIconMan.adoc | 0
doc/{modules => }/FvwmIdent.adoc | 0
doc/{modules => }/FvwmMFL.adoc | 0
doc/{modules => }/FvwmPager.adoc | 0
doc/{modules => }/FvwmPerl.adoc | 0
doc/{bin => }/FvwmPrompt.adoc | 0
doc/{modules => }/FvwmRearrange.adoc | 0
doc/{modules => }/FvwmScript.adoc | 0
doc/Makefile.am | 52 ++++++++++++----------------
doc/README | 8 -----
doc/{bin => }/fvwm-config.adoc | 0
doc/{bin => }/fvwm-convert-2.6.adoc | 0
doc/{bin => }/fvwm-menu-desktop.adoc | 0
doc/{bin => }/fvwm-root.adoc | 0
doc/{fvwm3 => }/fvwm3.adoc | 3 +-
doc/fvwm3commands.adoc | 7 ++++
25 files changed, 32 insertions(+), 39 deletions(-)
create mode 100644 doc/.gitignore
rename doc/{modules => }/FvwmAnimate.adoc (100%)
rename doc/{modules => }/FvwmAuto.adoc (100%)
rename doc/{modules => }/FvwmBacker.adoc (100%)
rename doc/{modules => }/FvwmButtons.adoc (100%)
rename doc/{bin => }/FvwmCommand.adoc (100%)
rename doc/{modules => }/FvwmConsole.adoc (100%)
rename doc/{modules => }/FvwmEvent.adoc (100%)
rename doc/{modules => }/FvwmForm.adoc (100%)
rename doc/{modules => }/FvwmIconMan.adoc (100%)
rename doc/{modules => }/FvwmIdent.adoc (100%)
rename doc/{modules => }/FvwmMFL.adoc (100%)
rename doc/{modules => }/FvwmPager.adoc (100%)
rename doc/{modules => }/FvwmPerl.adoc (100%)
rename doc/{bin => }/FvwmPrompt.adoc (100%)
rename doc/{modules => }/FvwmRearrange.adoc (100%)
rename doc/{modules => }/FvwmScript.adoc (100%)
rename doc/{bin => }/fvwm-config.adoc (100%)
rename doc/{bin => }/fvwm-convert-2.6.adoc (100%)
rename doc/{bin => }/fvwm-menu-desktop.adoc (100%)
rename doc/{bin => }/fvwm-root.adoc (100%)
rename doc/{fvwm3 => }/fvwm3.adoc (99%)
create mode 100644 doc/fvwm3commands.adoc
diff --git a/doc/.gitignore b/doc/.gitignore
new file mode 100644
index 00000000..07576799
--- /dev/null
+++ b/doc/.gitignore
@@ -0,0 +1 @@
+/*.section
diff --git a/doc/modules/FvwmAnimate.adoc b/doc/FvwmAnimate.adoc
similarity index 100%
rename from doc/modules/FvwmAnimate.adoc
rename to doc/FvwmAnimate.adoc
diff --git a/doc/modules/FvwmAuto.adoc b/doc/FvwmAuto.adoc
similarity index 100%
rename from doc/modules/FvwmAuto.adoc
rename to doc/FvwmAuto.adoc
diff --git a/doc/modules/FvwmBacker.adoc b/doc/FvwmBacker.adoc
similarity index 100%
rename from doc/modules/FvwmBacker.adoc
rename to doc/FvwmBacker.adoc
diff --git a/doc/modules/FvwmButtons.adoc b/doc/FvwmButtons.adoc
similarity index 100%
rename from doc/modules/FvwmButtons.adoc
rename to doc/FvwmButtons.adoc
diff --git a/doc/bin/FvwmCommand.adoc b/doc/FvwmCommand.adoc
similarity index 100%
rename from doc/bin/FvwmCommand.adoc
rename to doc/FvwmCommand.adoc
diff --git a/doc/modules/FvwmConsole.adoc b/doc/FvwmConsole.adoc
similarity index 100%
rename from doc/modules/FvwmConsole.adoc
rename to doc/FvwmConsole.adoc
diff --git a/doc/modules/FvwmEvent.adoc b/doc/FvwmEvent.adoc
similarity index 100%
rename from doc/modules/FvwmEvent.adoc
rename to doc/FvwmEvent.adoc
diff --git a/doc/modules/FvwmForm.adoc b/doc/FvwmForm.adoc
similarity index 100%
rename from doc/modules/FvwmForm.adoc
rename to doc/FvwmForm.adoc
diff --git a/doc/modules/FvwmIconMan.adoc b/doc/FvwmIconMan.adoc
similarity index 100%
rename from doc/modules/FvwmIconMan.adoc
rename to doc/FvwmIconMan.adoc
diff --git a/doc/modules/FvwmIdent.adoc b/doc/FvwmIdent.adoc
similarity index 100%
rename from doc/modules/FvwmIdent.adoc
rename to doc/FvwmIdent.adoc
diff --git a/doc/modules/FvwmMFL.adoc b/doc/FvwmMFL.adoc
similarity index 100%
rename from doc/modules/FvwmMFL.adoc
rename to doc/FvwmMFL.adoc
diff --git a/doc/modules/FvwmPager.adoc b/doc/FvwmPager.adoc
similarity index 100%
rename from doc/modules/FvwmPager.adoc
rename to doc/FvwmPager.adoc
diff --git a/doc/modules/FvwmPerl.adoc b/doc/FvwmPerl.adoc
similarity index 100%
rename from doc/modules/FvwmPerl.adoc
rename to doc/FvwmPerl.adoc
diff --git a/doc/bin/FvwmPrompt.adoc b/doc/FvwmPrompt.adoc
similarity index 100%
rename from doc/bin/FvwmPrompt.adoc
rename to doc/FvwmPrompt.adoc
diff --git a/doc/modules/FvwmRearrange.adoc b/doc/FvwmRearrange.adoc
similarity index 100%
rename from doc/modules/FvwmRearrange.adoc
rename to doc/FvwmRearrange.adoc
diff --git a/doc/modules/FvwmScript.adoc b/doc/FvwmScript.adoc
similarity index 100%
rename from doc/modules/FvwmScript.adoc
rename to doc/FvwmScript.adoc
diff --git a/doc/Makefile.am b/doc/Makefile.am
index b7da155a..9d4f6139 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,40 +1,32 @@
docdir = @FVWM_DOCDIR@
-MODULE_ADOCS = $(wildcard fvwm3/fvwm3.adoc bin/*.adoc modules/*.adoc)
+MODULE_ADOC = $(wildcard *.adoc)
-EXTRA_DIST = $(MODULE_ADOCS)
+EXTRA_DIST = $(MODULE_ADOC)
-if FVWM_BUILD_MANDOC
-BUILD_MANS = $(patsubst %.adoc,%, $(MODULE_ADOCS))
-else
-BUILD_MANS =
-endif
-
-all: docs
-docs: $(BUILD_MANS)
+nothing:
clean:
- rm -fr man1/
+ rm -f *.1 *.section
distclean-local: clean
if FVWM_BUILD_MANDOC
-QUIET_ASCIIDOC = @echo ' ' DOC ' ' $@'.1';
-
-%: %.adoc
- $(QUIET_ASCIIDOC) \
- NAME=`basename "$@" | "$(SED)" -e "${transform}"`; \
- $(ASCIIDOC) -b manpage $< -o "man1/$$NAME.1"
-
-install-data-local:
- install -d -m 755 $(DESTDIR)$(mandir)/man1/
- @for i in $(notdir $(BUILD_MANS)); do \
- NAME=`basename "$$i" | "$(SED)" -e "${transform}"`; \
- install -m 644 "man1/$$NAME.1" $(DESTDIR)$(mandir)/man1/; \
- done
-
-uninstall-local:
- @for i in $(notdir $(BUILD_MANS)); do \
- NAME=`basename "$$i" | "$(SED)" -e "${transform}"`; \
- rm -f "$(DESTDIR)$(mandir)/man1/$$NAME.1"; \
- done
+QUIET_ASCIIDOC = @echo ' ' DOC ' ' $@'';
+man1_MANS = $(patsubst %.adoc,%.1, $(MODULE_ADOC))
+EXTRACT_SECTIONS = commands
+SECTION_FILES = $(patsubst %,fvwm3_%.section, $(EXTRACT_SECTIONS))
+
+all: docs
+docs: $(man1_MANS)
+$(man1_MANS): $(SECTION_FILES)
+
+%.section: fvwm3.adoc
+ SECTION=$(patsubst fvwm3_%.section,%,$@); \
+ cat "$<" | \
+ "$(GREP)" -A 1000000 -- "^// BEGIN '$$SECTION'" | \
+ "$(GREP)" -B 1000000 -- "^// END '$$SECTION'" | \
+ "$(GREP)" -v "^// .* '$$SECTION'" > "$@"
+
+%.1: %.adoc
+ "$(ASCIIDOC)" -b manpage "$<" -o "$@"
endif
diff --git a/doc/README b/doc/README
index 85d7cceb..4dfba038 100644
--- a/doc/README
+++ b/doc/README
@@ -10,11 +10,3 @@ For more information about the specific markup available, see:
* https://asciidoctor.org/docs/asciidoc-writers-guide/
* https://asciidoctor.org/docs/user-manual/
-
-To add additional documents, see:
-
- doc/fvwm3/*.adoc
- doc/modules/*.adoc
-
-Documentation for modules now resides under `doc/`, rather than its own
-module.
diff --git a/doc/bin/fvwm-config.adoc b/doc/fvwm-config.adoc
similarity index 100%
rename from doc/bin/fvwm-config.adoc
rename to doc/fvwm-config.adoc
diff --git a/doc/bin/fvwm-convert-2.6.adoc b/doc/fvwm-convert-2.6.adoc
similarity index 100%
rename from doc/bin/fvwm-convert-2.6.adoc
rename to doc/fvwm-convert-2.6.adoc
diff --git a/doc/bin/fvwm-menu-desktop.adoc b/doc/fvwm-menu-desktop.adoc
similarity index 100%
rename from doc/bin/fvwm-menu-desktop.adoc
rename to doc/fvwm-menu-desktop.adoc
diff --git a/doc/bin/fvwm-root.adoc b/doc/fvwm-root.adoc
similarity index 100%
rename from doc/bin/fvwm-root.adoc
rename to doc/fvwm-root.adoc
diff --git a/doc/fvwm3/fvwm3.adoc b/doc/fvwm3.adoc
similarity index 99%
rename from doc/fvwm3/fvwm3.adoc
rename to doc/fvwm3.adoc
index b08db3a5..53e19f79 100644
--- a/doc/fvwm3/fvwm3.adoc
+++ b/doc/fvwm3.adoc
@@ -1757,6 +1757,7 @@ confuse some programs. For example, the xwd program refuses to make
screen shots when run from a complex function. To achieve the same
functionality you can use the *Read* or *PipeRead* command instead.
+// BEGIN 'commands'
== LIST OF FVWM COMMANDS
The command descriptions below are grouped together in the following
@@ -9575,7 +9576,7 @@ MenuFace DGradient 100 3 Red 20 Blue 30 Black 50 Grey
# 50% from yellow to red
Colorset 0 HGradient 128 3 Blue 1000 Green 1 Yellow 1000 Red
....
-
+// END 'commands'
== ENVIRONMENT
diff --git a/doc/fvwm3commands.adoc b/doc/fvwm3commands.adoc
new file mode 100644
index 00000000..41b340c2
--- /dev/null
+++ b/doc/fvwm3commands.adoc
@@ -0,0 +1,7 @@
+= FVWM3COMMANDS(1)
+
+== NAME
+
+fvwm3commands - fvwm build-in commands
+
+include::fvwm3_commands.section[]
--
2.30.2
