doc/local.mk

   1 # Make coreutils documentation.                         -*-Makefile-*-
   2 # This is included by the top-level Makefile.am.
   3
   4 # Copyright (C) 1995-2024 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 customization variable CHECK_NORMAL_MENU_STRUCTURE is necessary with
  29 # makeinfo versions ≥ 6.8.
  30 MAKEINFO = @MAKEINFO@ -c CHECK_NORMAL_MENU_STRUCTURE=1
  31
  32 # The following is necessary if the package name is 8 characters or longer.
  33 # If the info documentation would be split into 10 or more separate files,
  34 # then this is necessary even if the package name is 7 characters long.
  35 #
  36 # Tell makeinfo to put everything in a single info file: <package>.info.
  37 # Otherwise, it would also generate files with names like <package>.info-[123],
  38 # and those names all map to one 14-byte name (<package>.info-) on some crufty
  39 # old systems.
  40 AM_MAKEINFOFLAGS = --no-split
  41
  42 doc/constants.texi: $(top_srcdir)/src/tail.c $(top_srcdir)/src/shred.c
  43         $(AM_V_GEN)LC_ALL=C; export LC_ALL; \
  44         $(MKDIR_P) doc && \
  45         { sed -n -e 's/^#define \(DEFAULT_MAX[_A-Z]*\) \(.*\)/@set \1 \2/p' \
  46             $(top_srcdir)/src/tail.c && \
  47           sed -n -e \
  48               's/.*\(DEFAULT_PASSES\)[ =]* \([0-9]*\).*/@set SHRED_\1 \2/p'\
  49             $(top_srcdir)/src/shred.c; } > $@-t \
  50           && { cmp $@-t $@ >/dev/null 2>&1 || mv $@-t $@; rm -f $@-t; }
  51
  52 MAINTAINERCLEANFILES += doc/constants.texi
  53
  54 # Extended regular expressions to match word starts and ends.
  55 _W = (^|[^A-Za-z0-9_])
  56 W_ = ([^A-Za-z0-9_]|$$)
  57
  58 syntax_checks =         \
  59   sc-avoid-builtin      \
  60   sc-avoid-io           \
  61   sc-avoid-non-zero     \
  62   sc-avoid-path         \
  63   sc-avoid-timezone     \
  64   sc-avoid-zeroes       \
  65   sc-exponent-grouping  \
  66   sc-lower-case-var
  67
  68 texi_files = $(srcdir)/doc/*.texi
  69
  70 .PHONY: $(syntax_checks) check-texinfo
  71
  72 # List words/regexps here that should not appear in the texinfo documentation.
  73 check-texinfo: $(syntax_checks)
  74         $(AM_V_GEN)fail=0;                                              \
  75         grep '@url{' $(texi_files) && fail=1;                           \
  76         grep '\$$@"' $(texi_files) && fail=1;                           \
  77         grep -n '[^[:punct:]]@footnote' $(texi_files) && fail=1;        \
  78         grep -n filename $(texi_files)                                  \
  79             | $(EGREP) -v 'setfilename|[{]filename[}]'                  \
  80           && fail=1;                                                    \
  81         exit $$fail
  82
  83 sc-avoid-builtin:
  84         $(AM_V_GEN)$(EGREP) -i '$(_W)builtins?$(W_)' $(texi_files)      \
  85           && exit 1 || :
  86
  87 sc-avoid-path:
  88         $(AM_V_GEN)fail=0;                                              \
  89         $(EGREP) -i '$(_W)path(name)?s?$(W_)' $(texi_files)             \
  90           | $(EGREP) -v                                                 \
  91           'PATH=|path search|search path|@vindex PATH$$|@env[{]PATH[}]' \
  92           && fail=1;                                                    \
  93         exit $$fail
  94
  95 # Use "time zone", not "timezone".
  96 sc-avoid-timezone:
  97         $(AM_V_GEN)$(EGREP) timezone $(texi_files) && exit 1 || :
  98
  99 # Check for insufficient exponent grouping, e.g.,
 100 # @math{2^64} should be @math{2^{64}}.
 101 sc-exponent-grouping:
 102         $(AM_V_GEN)$(EGREP) '\{.*\^[0-9][0-9]' $(texi_files) && exit 1 || :
 103
 104 # Say I/O, not IO.
 105 sc-avoid-io:
 106         $(AM_V_GEN)$(EGREP) '$(_W)IO$(W_)' $(texi_files) && exit 1 || :
 107
 108 # I prefer nonzero over non-zero.
 109 sc-avoid-non-zero:
 110         $(AM_V_GEN)$(EGREP) non-zero $(texi_files) && exit 1 || :
 111
 112 # Use "zeros", not "zeroes" (nothing wrong with "zeroes"; just be consistent).
 113 sc-avoid-zeroes:
 114         $(AM_V_GEN)$(EGREP) -i '$(_W)zeroes$(W_)' $(texi_files) \
 115           && exit 1 || :
 116
 117 # The quantity inside @var{...} should not contain upper case letters.
 118 # The leading backslash exemption is to permit in-macro uses like
 119 # @var{\varName\} where the upper case letter is part of a parameter name.
 120 find_upper_case_var =           \
 121   '/\@var\{/ or next;           \
 122    while (/\@var\{(.+?)}/g)     \
 123      {                          \
 124        $$v = $$1;               \
 125        $$v =~ /[A-Z]/ && $$v !~ /^\\/ and (print "$$ARGV:$$.:$$_"), $$m = 1 \
 126      }                          \
 127    END {$$m and (warn "$@: do not use upper case in \@var{...}\n"), exit 1}'
 128 sc-lower-case-var:
 129         $(AM_V_GEN)$(PERL) -e 1 || { echo $@: skipping test; exit 0; }; \
 130           $(PERL) -lne $(find_upper_case_var) $(texi_files)
 131
 132 check-local: check-texinfo