doc/local.mk

   1 # Make coreutils documentation.                         -*-Makefile-*-
   2 # This is included by the top-level Makefile.am.
   3
   4 # Copyright (C) 1995-2023 Free Software Foundation, Inc.
   5
   6 # This program is free software: you can redistribute it and/or modify
   7 # it under the terms of the GNU General Public License as published by
   8 # the Free Software Foundation, either version 3 of the License, or
   9 # (at your option) any later version.
  10
  11 # This program is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 # GNU General Public License for more details.
  15
  16 # You should have received a copy of the GNU General Public License
  17 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
  18
  19 info_TEXINFOS = doc/coreutils.texi
  20
  21 doc_coreutils_TEXINFOS = \
  22   doc/perm.texi \
  23   doc/parse-datetime.texi \
  24   doc/constants.texi \
  25   doc/fdl.texi \
  26   doc/sort-version.texi
  27
  28 # The following is necessary if the package name is 8 characters or longer.
  29 # If the info documentation would be split into 10 or more separate files,
  30 # then this is necessary even if the package name is 7 characters long.
  31 #
  32 # Tell makeinfo to put everything in a single info file: <package>.info.
  33 # Otherwise, it would also generate files with names like <package>.info-[123],
  34 # and those names all map to one 14-byte name (<package>.info-) on some crufty
  35 # old systems.
  36 AM_MAKEINFOFLAGS = --no-split
  37
  38 doc/constants.texi: $(top_srcdir)/src/tail.c $(top_srcdir)/src/shred.c
  39         $(AM_V_GEN)LC_ALL=C; export LC_ALL; \
  40         $(MKDIR_P) doc && \
  41         { sed -n -e 's/^#define \(DEFAULT_MAX[_A-Z]*\) \(.*\)/@set \1 \2/p' \
  42             $(top_srcdir)/src/tail.c && \
  43           sed -n -e \
  44               's/.*\(DEFAULT_PASSES\)[ =]* \([0-9]*\).*/@set SHRED_\1 \2/p'\
  45             $(top_srcdir)/src/shred.c; } > $@-t \
  46           && { cmp $@-t $@ >/dev/null 2>&1 || mv $@-t $@; rm -f $@-t; }
  47
  48 MAINTAINERCLEANFILES += doc/constants.texi
  49
  50 # Extended regular expressions to match word starts and ends.
  51 _W = (^|[^A-Za-z0-9_])
  52 W_ = ([^A-Za-z0-9_]|$$)
  53
  54 syntax_checks =         \
  55   sc-avoid-builtin      \
  56   sc-avoid-io           \
  57   sc-avoid-non-zero     \
  58   sc-avoid-path         \
  59   sc-avoid-timezone     \
  60   sc-avoid-zeroes       \
  61   sc-exponent-grouping  \
  62   sc-lower-case-var
  63
  64 texi_files = $(srcdir)/doc/*.texi
  65
  66 .PHONY: $(syntax_checks) check-texinfo
  67
  68 # List words/regexps here that should not appear in the texinfo documentation.
  69 check-texinfo: $(syntax_checks)
  70         $(AM_V_GEN)fail=0;                                              \
  71         grep '@url{' $(texi_files) && fail=1;                           \
  72         grep '\$$@"' $(texi_files) && fail=1;                           \
  73         grep -n '[^[:punct:]]@footnote' $(texi_files) && fail=1;        \
  74         grep -n filename $(texi_files)                                  \
  75             | $(EGREP) -v 'setfilename|[{]filename[}]'                  \
  76           && fail=1;                                                    \
  77         exit $$fail
  78
  79 sc-avoid-builtin:
  80         $(AM_V_GEN)$(EGREP) -i '$(_W)builtins?$(W_)' $(texi_files)      \
  81           && exit 1 || :
  82
  83 sc-avoid-path:
  84         $(AM_V_GEN)fail=0;                                              \
  85         $(EGREP) -i '$(_W)path(name)?s?$(W_)' $(texi_files)             \
  86           | $(EGREP) -v                                                 \
  87           'PATH=|path search|search path|@vindex PATH$$|@env[{]PATH[}]' \
  88           && fail=1;                                                    \
  89         exit $$fail
  90
  91 # Use "time zone", not "timezone".
  92 sc-avoid-timezone:
  93         $(AM_V_GEN)$(EGREP) timezone $(texi_files) && exit 1 || :
  94
  95 # Check for insufficient exponent grouping, e.g.,
  96 # @math{2^64} should be @math{2^{64}}.
  97 sc-exponent-grouping:
  98         $(AM_V_GEN)$(EGREP) '\{.*\^[0-9][0-9]' $(texi_files) && exit 1 || :
  99
 100 # Say I/O, not IO.
 101 sc-avoid-io:
 102         $(AM_V_GEN)$(EGREP) '$(_W)IO$(W_)' $(texi_files) && exit 1 || :
 103
 104 # I prefer nonzero over non-zero.
 105 sc-avoid-non-zero:
 106         $(AM_V_GEN)$(EGREP) non-zero $(texi_files) && exit 1 || :
 107
 108 # Use "zeros", not "zeroes" (nothing wrong with "zeroes"; just be consistent).
 109 sc-avoid-zeroes:
 110         $(AM_V_GEN)$(EGREP) -i '$(_W)zeroes$(W_)' $(texi_files) \
 111           && exit 1 || :
 112
 113 # The quantity inside @var{...} should not contain upper case letters.
 114 # The leading backslash exemption is to permit in-macro uses like
 115 # @var{\varName\} where the upper case letter is part of a parameter name.
 116 find_upper_case_var =           \
 117   '/\@var\{/ or next;           \
 118    while (/\@var\{(.+?)}/g)     \
 119      {                          \
 120        $$v = $$1;               \
 121        $$v =~ /[A-Z]/ && $$v !~ /^\\/ and (print "$$ARGV:$$.:$$_"), $$m = 1 \
 122      }                          \
 123    END {$$m and (warn "$@: do not use upper case in \@var{...}\n"), exit 1}'
 124 sc-lower-case-var:
 125         $(AM_V_GEN)$(PERL) -e 1 || { echo $@: skipping test; exit 0; }; \
 126           $(PERL) -lne $(find_upper_case_var) $(texi_files)
 127
 128 check-local: check-texinfo