reworking doc build

This commit is contained in:
gdr 2012-08-26 02:27:36 +00:00
parent 2ea55d1d9b
commit e55fb1c59f
10 changed files with 329 additions and 13 deletions

1
doc/.cvsignore Normal file
View File

@ -0,0 +1 @@
gen

31
doc/GNUmakefile Normal file
View File

@ -0,0 +1,31 @@
#
# Documentation for the GNO project (proper)
#
SRCROOT = ..
WEB_HOME_BASE =
SUBPROJECTS = refs refs.aug96
include $(SRCROOT)/doc/etc/constpriv.mk
include $(SRCROOT)/doc/etc/const.mk
WEB_HOME = $(DOCROOT_INSECURE)
# We don't have any default targets as the top level in the hierarchy
# is not maintained by this repository.
TARGETS =
default: build
install:
@for s in X $(SUBPROJECTS); do \
[ "$$s" = X ] && continue; \
[ -d "$$s" ] || continue; \
(cd $$s; $(MAKE) $(MFLAGS) $@); \
done
include $(SRCROOT)/doc/etc/rules.mk
include $(SRCROOT)/doc/etc/tailcat.mk
clobber::
-/bin/rm -rf $(OUTPUT_DIR)

41
doc/README Normal file
View File

@ -0,0 +1,41 @@
Unlike the rest of the source, we don't build the docs under
the GS itself. Currently (summer 2012) the build machine is
a CentOS 5.x server. (The GS cannot handle the tool chain
currently used to build docs.) Incidentally, this is why the
makefiles in this hierarchy are called GNUmakefile instead of
Makefile; there is no GNU make for the GS, so you can't
accidentally trigger a make in this directory on a GS (or if
you do, it won't get very far.
CONFIGURATION
=============
Create the file etc/constpriv.mk and add this line:
GNO_PUBLIC_HTML = /home/myname/public_html/gno
Of course, change that to whereever you prefer. This file is
ignored by the repository, so you will not see it checked in.
DOCUMENT BUILD
==============
To build the documents, you will need to have installed:
GNU make
docbook
tetex-latex
latex-dvips
latex2html
In order to build the reference manuals, do the following:
make
That will cause the documentation to be generated into the 'gen'
hierarchy.
DOCUMENT INSTALLATION
=====================
This should normally only be done for the official GNO web server.
To install the reference manuals:
make install

1
doc/etc/.cvsignore Normal file
View File

@ -0,0 +1 @@
constpriv.mk

39
doc/etc/const.mk Normal file
View File

@ -0,0 +1,39 @@
#
# $Id: const.mk,v 1.1 2012/08/26 02:27:35 gdr Exp $
#
# Before this file is included, it is assumed that you have included
# the constpriv.mk file, which needs to define these variables:
#
# GNO_PUBLIC_HTML
# The directory where the GNO web pages are anchored. This
# top level directory is not managed by these files, but
# the files there need to reference these files. If you are
# not building this for the official GNO web site, you can
# just point this at a scratch directory somewhere.
#
# This is the name and address that will be given as contact info
# at the bottom of each of the HTML pages. Do NOT use '<' or '>' in the
# address.
NAME = Devin Reade
ADDRESS = gdr@gno.org
OUTPUT_DIR = $(SRCROOT)/doc/gen
DOCROOT = $(OUTPUT_DIR)
DOCROOT_INSECURE = $(OUTPUT_DIR)/insecure/gno
DOCROOT_SECURE = $(OUTPUT_DIR)/secure/gno
HTTP_SERVER = www.gno.org
HTTP_PORT = # :81
HTTPS_PORT = # :8443
FTP_SERVER = ftp.gno.org
DATE = $(SRCROOT)/etc/getdate -date
BUILD_FILES = GNUmakefile $(HEAD_PAGE) $(TAIL_PAGE) \
$(SRCROOT)/doc/etc/const.mk \
$(SRCROOT)/doc/etc/rules.mk \
$(SRCROOT)/doc/etc/tailcat.mk
# This is where the files will eventually wind up.
TARGET_DIR = $(GNO_PUBLIC_HTML)/$(WEB_HOME_BASE)

74
doc/etc/getdate Executable file
View File

@ -0,0 +1,74 @@
#! /usr/bin/perl -s
#
# Extract the date from the RCS Id string in a file.
#
# $Id: getdate,v 1.1 2012/08/26 02:27:36 gdr Exp $
#
use strict;
my @month;
push(@month,
"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep",
"Oct", "Nov", "Dec" );
# for ($i=0; $i<12; $i++) {
# printf("month %d is %s\n", $i, $month[$i]);
# }
my $printdate = 0;
my $printversion = 0;
if (defined($::date)) {
$printdate = 1;
}
if (defined($::version)) {
$printversion = 1;
}
my %sortedDates;
my %sortedVersions;
my $date = "(unspecified date)";
my $version = "(unspecified version)";
while(<>) {
if (/\$Id([^\$]*)\$/) {
$_ = $1;
if (/^:\s+(\S+)\s+(\S+)\s+(\S+)\s+(\S+)\s+/) {
my $file=$1;
my $v=$2;
my $rawdate=$3;
my $time=$4;
if ($rawdate =~ m,(\d+)[-/](\d+)[-/](\d+),) {
my $year = $1;
my $m = $2;
my $day = $3;
my $mon = @month[int($2) - 1];
my $d = "$day $mon $year";
my $fakedate = int($day) + 100 * int($m) + 10000 * int($year);
$sortedDates{"$fakedate"} = $d;
$sortedVersions{"$fakedate"} = $v;
}
}
}
}
my @fakes = sort(keys(%sortedDates));
my $lastFake = pop @fakes;
if (defined($lastFake)) {
$date = $sortedDates{$lastFake};
$version = $sortedVersions{$lastFake};
}
if ($printdate) {
printf("%s\n", $date);
} elsif ($printversion) {
printf("%s\n", $version);
} else {
printf("getdate: bad invocation\n");
exit(1);
}
exit(0);

77
doc/etc/rules.mk Normal file
View File

@ -0,0 +1,77 @@
#
# $Id: rules.mk,v 1.1 2012/08/26 02:27:36 gdr Exp $
#
$(WEB_HOME)/%.gif: %.gif
install -m644 $< $@
$(WEB_HOME)/%.png: %.png
install -m644 $< $@
$(WEB_HOME)/%.pdf: %.pdf
install -m644 $< $@
$(WEB_HOME)/%.txt: %.txt
install -m644 $< $@
build: buildLocal webHome $(TARGETS) webHomePerms $(BUILD_FILES)
@for s in X $(SUBPROJECTS); do \
[ "$$s" = X ] && continue; \
[ -d "$$s" ] || continue; \
(cd $$s; $(MAKE) $(MFLAGS) $@); \
done
buildLocal::
@true
webHome:
@if [ -z "$(WEB_HOME)" ]; then \
echo "WEB_HOME not set"; \
exit 1; \
fi; \
[ -d $(WEB_HOME) ] || mkdir -p $(WEB_HOME)
webHomePerms:
@if [ -z "$(WEB_HOME)" ]; then \
echo "WEB_HOME not set"; \
exit 1; \
fi; \
find $(WEB_HOME) -type d \! -perm 0755 -exec chmod 0755 {} \; ; \
find $(WEB_HOME) -type f \! -perm 0644 -exec chmod 644 {} \;
install::
@/bin/rm -rf $(TARGET_DIR)
install -d -m755 $(TARGET_DIR)
@echo "copying files to $(TARGET_DIR)"; \
cd $(WEB_HOME); tar -cf - . | \
(cd $(TARGET_DIR); tar -xpBf -);
@echo "setting permissions on $(TARGET_DIR)"; \
find $(TARGET_DIR) -type d \! -perm 0755 -exec chmod 0755 {} \; ; \
find $(TARGET_DIR) -type f \! -perm 0644 -exec chmod 644 {} \;
clean::
rm -f *~
@for s in X $(SUBPROJECTS); do \
[ "$$s" = X ] && continue; \
[ -d "$$s" ] || continue; \
(cd $$s; $(MAKE) $(MFLAGS) $@); \
done
clobber:: clean
buildDocbookHtml:: clean
@if [ -z "$(DOCBOOK_TOP)" ]; then \
echo "DOCBOOK_TOP is not set"; \
exit 1; \
fi
@htmldir="$(WEB_HOME)/html"; \
[ -d $$htmldir ] || mkdir -p $$htmldir; \
echo docbook2html -o $$htmldir $(DOCBOOK_TOP); \
docbook2html -o $$htmldir $(DOCBOOK_TOP)
# -cp -p *.png $(HTML_DIR)
buildDocbookPdf::
@[ -d $(WEB_HOME) ] || mkdir -p $(WEB_HOME)
@date
docbook2pdf -o $(WEB_HOME) $(DOCBOOK_TOP)
@date

23
doc/etc/tailcat.mk Normal file
View File

@ -0,0 +1,23 @@
#
# $Id: tailcat.mk,v 1.1 2012/08/26 02:27:36 gdr Exp $
#
$(WEB_HOME):
mkdir -p $(WEB_HOME)
$(WEB_HOME)/%.html: %.html $(HEAD_PAGE) $(HEAD_PAGE_1) $(TAIL_PAGE) Makefile
@echo "making $@"; \
date="`$(DATE) < $<`"; \
cat $(HEAD_PAGE) $(HEAD_PAGE_1) $*.html $(TAIL_PAGE) | perl -p \
-e "s,%%DATE%%,$$date,g;" \
-e 's,%%HTTP_SERVER%%,$(HTTP_SERVER),g;' \
-e 's,%%HTTP_PORT%%,$(HTTP_PORT),g;' \
-e 's,%%HTTPS_PORT%%,$(HTTPS_PORT),g;' \
-e 's,%%FTP_SERVER%%,$(FTP_SERVER),g;' \
-e 's,%%HTML_TITLE%%,$(HTML_TITLE),g;' \
$(TAILCAT_LOCAL_REPLACEMENTS) \
> $@
@if [ "$(FIX_PERMS)" != "no" ]; then \
chmod 644 $@; \
fi
@$(WEBLINT) $@

View File

@ -0,0 +1,40 @@
#
# $Id: GNUmakefile,v 1.1 2012/08/26 02:27:36 gdr Exp $
#
SRCROOT = ../..
WEB_HOME_BASE = refs.aug96
SUBPROJECTS =
include $(SRCROOT)/doc/etc/constpriv.mk
include $(SRCROOT)/doc/etc/const.mk
WEB_HOME = $(DOCROOT_INSECURE)/$(WEB_HOME_BASE)
HEAD_PAGE =
TAIL_PAGE =
TARGETS = literalCopy
#INSTALL_REAL = $(GNO_PUBLIC_HTML)/refs.aug96
#INSTALL_FAKE = $(INSTALL_REAL)-test
MAIN_PAGES = gsh.12.html \
gsh.3.html \
gsh.4.html \
gsh.5.html \
install.html \
kern.html \
man1.html \
man2.html \
man3.html \
man4.html
default: build
literalCopy:
@for f in $(MAIN_PAGES); do \
echo install -m644 $$f $(WEB_HOME); \
install -m644 $$f $(WEB_HOME); \
done
include $(SRCROOT)/doc/etc/rules.mk
include $(SRCROOT)/doc/etc/tailcat.mk

View File

@ -1,5 +1,5 @@
#
# $Id: GNUmakefile,v 1.1 2012/08/25 07:19:00 gdr Exp $
# $Id: GNUmakefile,v 1.2 2012/08/26 02:27:36 gdr Exp $
#
@ -11,8 +11,6 @@ include $(SRCROOT)/doc/etc/constpriv.mk
include $(SRCROOT)/doc/etc/const.mk
WEB_HOME = $(DOCROOT_INSECURE)/$(WEB_HOME_BASE)
HTML_DIR = $(WEB_HOME)/html
TARGET_DIR = $(GNO_PUBLIC_HTML)/$(WEB_HOME_BASE)
HEAD_PAGE =
TAIL_PAGE =
TARGETS = buildDocbookHtml buildDocbookPdf
@ -21,17 +19,8 @@ DOCBOOK_TOP = gsh.docbook
default: build
clean::
/bin/rm -rf $(HTML_DIR)
/bin/rm -rf $(WEB_HOME)/html
include $(SRCROOT)/doc/etc/rules.mk
include $(SRCROOT)/doc/etc/tailcat.mk
install:
@/bin/rm -rf $(TARGET_DIR)
install -d -m755 $(TARGET_DIR)
@echo "copying files to $(TARGET_DIR)"; \
cd $(WEB_HOME); tar -cf - . | \
(cd $(TARGET_DIR); tar -xpBf -);
@echo "setting permissions on $(TARGET_DIR)"; \
find $(TARGET_DIR) -type d \! -perm 0755 -exec chmod 0755 {} \; ; \
find $(TARGET_DIR) -type f \! -perm 0644 -exec chmod 644 {} \;