From 58422d1a4a82ba48e045a9603bd5ee7916f6c922 Mon Sep 17 00:00:00 2001 From: Adam Spragg <adam@spra.gg> Date: Tue, 28 Jun 2022 17:37:18 +0100 Subject: doc: Generate the man page from markdown Because who wants to hand-write groff markup these days? This adds pandoc(1) as a build-dependency. It uses PHP Markdown Extra definition lists, which pandoc uses for e.g. command option/explanation lists. Because this definition list format is non-standard it might not render as intended on many markdown viewers, but pandoc generates "better" man page output with it. --- .gitignore | 2 + Makefile | 13 ++++--- README | 1 + man1/metastore.1 | 82 ---------------------------------------- metastore.md | 111 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ metastore.txt | 90 -------------------------------------------- 6 files changed, 122 insertions(+), 177 deletions(-) delete mode 100644 man1/metastore.1 create mode 100644 metastore.md delete mode 100644 metastore.txt diff --git a/.gitignore b/.gitignore index d49e271..8593404 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,8 @@ Makefile.dep /bin/ +/man1/ + *~ *.patch diff --git a/Makefile b/Makefile index 364825c..f284f5a 100644 --- a/Makefile +++ b/Makefile @@ -30,7 +30,7 @@ DOCS := \ LICENSE.GPLv2 \ NEWS \ README \ - metastore.txt \ + metastore.md \ examples \ metastore_COMP := CC @@ -85,7 +85,7 @@ SLL_EXT := .a ### Default target -all: libs bins +all: libs bins man1/metastore.1 bins: $(BINS) libs: $(LIBS) @@ -315,9 +315,10 @@ $(SDEP): $(SRCS) $(PROJ_DIR)Makefile fi \ done) >>$(SDEP) -$(DOCS_DIR)%.txt: $(MANS_DIR)/man1/%.1 - @echo " GROFF $@" - $(HIDE)groff -mandoc -Kutf8 -Tutf8 $^ | col -bx >$@ +$(MANS_DIR)man1/metastore.1: $(DOCS_DIR)metastore.md + @mkdir -p $(MANS_DIR)man1 + @echo " PANDOC $@" + $(HIDE)pandoc -s --shift-heading-level=-1 -f markdown -t man $^ >$@ ### Rules for phony targets @@ -327,10 +328,12 @@ clean: $(HIDE)$(RM) $(addprefix $(BINS_DIR),$(BINS)) \ $(addprefix $(LIBS_DIR),$(LIBS_ALL_FILES)) \ $(addprefix $(OBJS_DIR),$(OBJS)) \ + $(addprefix $(MANS_DIR),$(MANS)) \ $(SDEP) distclean: clean $(HIDE)(find \ + $(MANS_DIR) \ $(OBJS_DIR) \ $(LIBS_DIR) \ $(BINS_DIR) \ diff --git a/README b/README index 02b0545..d5a9393 100644 --- a/README +++ b/README @@ -53,6 +53,7 @@ Requirements - Linux - GNU make - C99 compiler, like gcc or clang +- pandoc - libbsd diff --git a/man1/metastore.1 b/man1/metastore.1 deleted file mode 100644 index 063e3e3..0000000 --- a/man1/metastore.1 +++ /dev/null @@ -1,82 +0,0 @@ -.TH metastore "1" "January 2016" -.\" -.SH NAME -metastore \- stores and restores filesystem metadata -.\" -.SH SYNOPSIS -\fBmetastore\fR \fIACTION\fR [\fIOPTION...\fR] [\fIPATH...\fR] -.\" -.SH DESCRIPTION -Stores or restores metadata (owner, group, permissions, xattrs and optionally -mtime) for a filesystem tree. This can be used to preserve the metadata in -situations where it is usually not stored (git and tar for example) or as -a tripwire like mechanism to detect any changes to metadata. Note that e.g. -SELinux stores its labels in xattrs so care should be taken when applying -stored metadata to make sure that system security is not compromised. -.\" -.SH ACTIONS -.TP -.B \-c, \-\-compare -Shows the difference between the stored and real metadata. -.TP -.B \-s, \-\-save -Saves the current metadata to ./.metadata or to the specified file -(see \-\-file option below). -.TP -.B \-a, \-\-apply -Attempts to apply the stored metadata to the file system. -.TP -.B \-d, \-\-dump -Dumps stored (if no \fIPATH\fR is given) or real metadata (if \fIPATH\fR is -present, e.g. \fB./\fR) in human-readable form. - -This action is meant only as a helpful debugging facility or merge conflict -helper. Do not ever compare its output generated using different metastore -version. Do not rely on current output format (especially in batch scripts), -because it may change in future without prior notice. -.TP -.B \-h, \-\-help -Prints a help message and exits. -.\" -.SH OPTIONS -.TP -.B \-v, \-\-verbose -Causes metastore to print more verbose messages. Can be repeated more than -once for even more verbosity. -.TP -.B \-q, \-\-quiet -Causes metastore to print less verbose messages. Can be repeated more than -once for even less verbosity. -.TP -.B \-m, \-\-mtime -Causes metastore to also take mtime into account for the compare or apply actions. -.TP -.B \-e, \-\-empty\-dirs -Also attempts to recreate missing empty directories. May be useful where -empty directories are not tracked (e.g. by git or cvs). -Only works in combination with the \fBapply\fR option. -.TP -.B -E, --remove-empty-dirs -Also attempts to remove empty directories missing from the metadata. May be -useful where empty directories are not tracked (e.g. by git or cvs). Only -works in combination with the \fBapply\fR option. -.TP -.B \-g, \-\-git -Prevents metastore from omitting .git directories. -.TP -.B \-f <file>, \-\-file <file> -Causes the metadata to be saved, read from the specified file rather -than ./.metadata. -.\" -.SH PATHS -If no path is specified, metastore will use the current directory as the basis -for the actions. This is the recommended way of executing metastore. -Alternatively, one or more paths can be specified and they will each be -examined. Later invocations should be made using the exact same paths to -ensure that the stored metadata is interpreted correctly. -.\" -.SH AUTHORS -metastore was created by David Härdeman in 2007-2008. -Now it is maintained by Przemysław Pawełczyk. -All source code contributors are listed in the AUTHORS file. - diff --git a/metastore.md b/metastore.md new file mode 100644 index 0000000..2d2ba83 --- /dev/null +++ b/metastore.md @@ -0,0 +1,111 @@ +# metastore(1) January 2016 | General Commands Manual + +## NAME + +metastore - stores and restores filesystem metadata + + +## SYNOPSIS + +**metastore** *ACTION* \[*OPTION...*\] \[*PATH...*\] + + +## DESCRIPTION + +Stores or restores metadata (owner, group, permissions, xattrs and optionally +mtime) for a filesystem tree. This can be used to preserve the metadata in +situations where it is usually not stored ([git(1)](GIT) and [tar(1)](TAR) for +example) or as a tripwire like mechanism to detect any changes to metadata. +Note that e.g. SELinux stores its labels in xattrs so care should be taken when +applying stored metadata to make sure that system security is not compromised. + + +## ACTIONS + +**-c, \-\-compare** + +: Shows the difference between the stored and real metadata. + +**-s, \-\-save** + +: Saves the current metadata to `./.metadata` or to the specified file + (see `--file` option below). + +**-a, \-\-apply** + +: Attempts to apply the stored metadata to the file system. + +**-d, \-\-dump** + +: Dumps stored (if no *PATH* is given) or real metadata (if *PATH* is + present, e.g. `./`) in human-readable form. + + This action is meant only as a helpful debugging facility or merge + conflict helper. Do not ever compare its output generated using + different metastore version. Do not rely on current output format + (especially in batch scripts), because it may change in future without + prior notice. + +**-h, \-\-help** + +: Prints a help message and exits. + + +## OPTIONS + +**-v, \-\-verbose** + +: Causes metastore to print more verbose messages. Can be repeated more + than once for even more verbosity. + +**-q, \-\-quiet** + +: Causes metastore to print less verbose messages. Can be repeated more + than once for even less verbosity. + +**-m, \-\-mtime** + +: Causes metastore to also take mtime into account for the compare or + apply actions. + +**-e, \-\-empty-dirs** + +: Also attempts to recreate missing empty directories. May be useful where + empty directories are not tracked (e.g. by [git(1)](GIT) or + [cvs(1)](CVS)). Only works in combination with the `--apply` option. + +**-E, \-\-remove-empty-dirs** + +: Also attempts to remove empty directories missing from the metadata. May + be useful where empty directories are not tracked (e.g. by [git(1)](GIT) + or [cvs(1)](CVS)). Only works in combination with the `--apply` option. + +**-g, \-\-git** + +: Prevents metastore from omitting `.git` directories. + +**-f \<file\>, \-\-file \<file\>** + +: Causes the metadata to be saved, read from the specified file rather + than `./.metadata`. + + +## PATHS + +If no path is specified, `metastore` will use the current directory as the basis +for the actions. This is the recommended way of executing metastore. +Alternatively, one or more paths can be specified and they will each be +examined. Later invocations should be made using the exact same paths to ensure +that the stored metadata is interpreted correctly. + + +## AUTHORS + +`metastore` was created by David Härdeman in 2007-2008. Now it is maintained by +Przemysław Pawełczyk. All source code contributors are listed in the `AUTHORS` +file. + + +[CVS]: man:cvs(1) +[GIT]: man:git(1) +[TAR]: man:tar(1) diff --git a/metastore.txt b/metastore.txt deleted file mode 100644 index 7edb5a8..0000000 --- a/metastore.txt +++ /dev/null @@ -1,90 +0,0 @@ -metastore(1) General Commands Manual metastore(1) - - - -NAME - metastore - stores and restores filesystem metadata - -SYNOPSIS - metastore ACTION [OPTION...] [PATH...] - -DESCRIPTION - Stores or restores metadata (owner, group, permissions, xattrs and - optionally mtime) for a filesystem tree. This can be used to preserve - the metadata in situations where it is usually not stored (git and tar - for example) or as a tripwire like mechanism to detect any changes to - metadata. Note that e.g. SELinux stores its labels in xattrs so care - should be taken when applying stored metadata to make sure that system - security is not compromised. - -ACTIONS - -c, --compare - Shows the difference between the stored and real metadata. - - -s, --save - Saves the current metadata to ./.metadata or to the specified - file (see --file option below). - - -a, --apply - Attempts to apply the stored metadata to the file system. - - -d, --dump - Dumps stored (if no PATH is given) or real metadata (if PATH is - present, e.g. ./) in human-readable form. - - This action is meant only as a helpful debugging facility or - merge conflict helper. Do not ever compare its output generated - using different metastore version. Do not rely on current output - format (especially in batch scripts), because it may change in - future without prior notice. - - -h, --help - Prints a help message and exits. - -OPTIONS - -v, --verbose - Causes metastore to print more verbose messages. Can be repeated - more than once for even more verbosity. - - -q, --quiet - Causes metastore to print less verbose messages. Can be repeated - more than once for even less verbosity. - - -m, --mtime - Causes metastore to also take mtime into account for the compare - or apply actions. - - -e, --empty-dirs - Also attempts to recreate missing empty directories. May be use‐ - ful where empty directories are not tracked (e.g. by git or - cvs). Only works in combination with the apply option. - - -E, --remove-empty-dirs - Also attempts to remove empty directories missing from the meta‐ - data. May be useful where empty directories are not tracked - (e.g. by git or cvs). Only works in combination with the apply - option. - - -g, --git - Prevents metastore from omitting .git directories. - - -f <file>, --file <file> - Causes the metadata to be saved, read from the specified file - rather than ./.metadata. - -PATHS - If no path is specified, metastore will use the current directory as - the basis for the actions. This is the recommended way of executing - metastore. Alternatively, one or more paths can be specified and they - will each be examined. Later invocations should be made using the exact - same paths to ensure that the stored metadata is interpreted correctly. - -AUTHORS - metastore was created by David Härdeman in 2007-2008. Now it is main‐ - tained by Przemysław Pawełczyk. All source code contributors are - listed in the AUTHORS file. - - - - - January 2016 metastore(1) -- cgit v1.2.1