c67d223854
* doc/Makefile.am (GENDOCS): Use the version from the tar repository. (manual): Set the DISTRIN rendition. (manual-rebuild): New goal. * doc/README.manual: New file. Instructions for maintainers on how to update web documentation. * doc/gendocs.sh: A version from gnulib fixed as per https://lists.gnu.org/archive/html/bug-gnulib/2021-03/msg00002.html. * doc/gendocs_template: Updated version from gnulib. * doc/intern.texi: Fix the use of UNREVISED. * doc/tar.texi: Fix the use of GNUTAR.
92 lines
2.7 KiB
Plaintext
92 lines
2.7 KiB
Plaintext
* Overview
|
||
|
||
This file is a short instruction for maintainers on how to create and
|
||
publish the online version of the Tar Manual.
|
||
|
||
In the sections below we assume that the tar project has been properly
|
||
cloned from the git repo, bootstrapped and configured. We also assume
|
||
that top-level directory of the project is the current local directory.
|
||
|
||
* Creating the web manual
|
||
|
||
To create the online version of the documentation, run
|
||
|
||
make -C doc manual-rebuild
|
||
|
||
This will create the directory doc/manual populated with the tar
|
||
documentation files in various formats. If the doc/manual directory
|
||
already exists, it will be removed prior to rebuilding.
|
||
|
||
The command produces very copious output. We advise you to examine it
|
||
closely to make sure no error messages slip your attention.
|
||
|
||
For the completeness sake, there are two more Makefile goals related
|
||
to the online manual:
|
||
|
||
** make -C doc clean-local
|
||
|
||
Removes the doc/manual directory, if it exists.
|
||
|
||
** make -C doc manual
|
||
|
||
Builds the doc/manual, unless it already exists.
|
||
|
||
* CVS Repository
|
||
|
||
The online tar manual[1] is a part of tar web pages[2] and is
|
||
traditionally maintained in the CVS repository[3]. To publish the
|
||
generated documentation, you will need first to check out tar web
|
||
pages from the CVS. To do so, run
|
||
|
||
cvs -z3 -d:ext:<username>@cvs.savannah.gnu.org:/web/tar co tar
|
||
|
||
where <username> is your user name on Savannah. For the rest of this
|
||
document we will assume that the checked out version of the tar web
|
||
pages resides in the ~/websrc/tar directory.
|
||
|
||
If you have already checked out the web pages, be sure to update them
|
||
before publishing:
|
||
|
||
cd ~/websrc/tar
|
||
cvs update
|
||
|
||
* Publishing
|
||
|
||
To publish the created manual, change to the tar top-level directory
|
||
and run:
|
||
|
||
rsync -avz --exclude CVS --delete manual ~/websrc/tar
|
||
|
||
This will synchronize the newly created manual pages with the content
|
||
of the CVS sandbox. Then, change to the ~/websrc/tar directory and
|
||
schedule any removed files for removal and any new files for addition
|
||
to the repository:
|
||
|
||
cvs diff --brief 2>&1 | sed -n 's/.*cannot find //p' | xargs cvs rm
|
||
cvs diff --brief 2>&1 | sed -n 's/^? //p' | xargs cvs add
|
||
|
||
Then commit your changes:
|
||
|
||
cvs commit
|
||
|
||
Once the changes are committed to CVS a job is scheduled on the server,
|
||
which synchronizes them with the content of the directory served by
|
||
the httpd daemon. Normally such synchronization happens within
|
||
several seconds from the commit.
|
||
|
||
For more information about CVS, please see its documentation[4].
|
||
|
||
* References
|
||
|
||
[1] https://www.gnu.org/software/tar/manual/
|
||
[2] https://www.gnu.org/software/tar/
|
||
[3] https://web.cvs.savannah.gnu.org/viewvc/tar/
|
||
[4] https://www.nongnu.org/cvs/#documentation
|
||
|
||
|
||
Local Variables:
|
||
mode: outline
|
||
paragraph-separate: "[ ]*$"
|
||
version-control: never
|
||
End:
|