[scotch] 09/12: restore debian version of dgscat.1

Wed Dec 20 07:14:43 UTC 2017

This is an automated email from the git hooks/post-receive script.

dparsons pushed a commit to tag debian/6.0.4.dfsg1-8
in repository scotch.

commit d7ca919ea5f5a777346f691372fcbc0d980c9c2a
Author: Drew Parsons <dparsons at debian.org>
Date:   Wed Dec 20 14:05:39 2017 +0800

    restore debian version of dgscat.1
    
    Provides documentation for dggath and gscat.
---
 debian/dgscat.1 | 136 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 debian/rules    |   6 +++
 2 files changed, 142 insertions(+)

diff --git a/debian/dgscat.1 b/debian/dgscat.1
new file mode 100644
index 0000000..3f743de
--- /dev/null
+++ b/debian/dgscat.1
@@ -0,0 +1,136 @@
+.\" Text adapted from original dgscat.1
+.TH dgscat 1 "August 03, 2010" "" "PT-Scotch user's manual"
+.SH NAME
+\fBdggath, dgscat, gscat \fP- convert distributed source graphs to or from centralized ones
+\fB
+.SH SYNOPSIS
+.nf
+.fam C
+\fBdggath\fP [\fIoptions\fP] [\fIigfile\fP] [\fIogfile\fP]
+.PP
+\fBdgscat\fP [\fIoptions\fP] [\fIigfile\fP] [\fIogfile\fP]
+.PP
+\fBgscat\fP [\fIoptions\fP] [\fIigfile\fP] [\fIogfile\fP]
+.fam T
+.fi
+.SH DESCRIPTION
+The \fBdggath\fP program gathers distributed graphs into centralized
+graphs. It reads a set of files \fIigfile\fP representing fragments of a
+distributed source graph, and writes them back on the form of a
+single centralized source graph \fIogfile\fP.
+.PP
+The \fBdgscat\fP program scatters centralized source graphs into
+distributed graphs. It reads a centralized source graph \fIigfile\fP and
+writes it back on the form of a set of files \fIogfile\fP representing
+fragments of the corresponding distributed source graph.
+.PP
+The \fBgscat\fP program does exactly the same as \fBdgscat\fP, but does not
+require to be run in a parallel environment. Since \fBgscat\fP processes
+the input centralized graph file as a text stream, it does not need
+to load the full graph in memory before building the distributed
+graph fragment files. It is therefore much less resource consuming,
+but does not allow for the checking of graph consistency, as it has
+no global vision of the graph structure.
+.PP
+When file names are not specified, data is read from standard input
+and written to standard output. Standard streams can also be
+explicitly represented by a dash '-'.
+.PP
+When the proper libraries have been included at compile time, \fBdggath\fP
+and \fBdgscat\fP can directly handle compressed graphs, both as input and
+output. A stream is treated as compressed whenever its name is
+postfixed with a compressed file extension, such as
+in 'brol.grf.bz2' or '-.gz'. The compression formats which can be
+supported are the bzip2 format ('.bz2'), the gzip format ('.gz'),
+and the lzma format ('.lzma', on input only).
+.PP
+\fBdggath\fP and \fBdgscat\fP base on implementations of the MPI interface to
+spread work across the processing elements. It is therefore not
+likely to be run directly, but instead through some launcher command
+such as \fBmpirun\fP.
+.SH DISTRIBUTED FILE NAMES
+In order to tell whether programs should read from, or write to, a
+single file located on only one processor, or to multiple instances
+of the same file on all of the processors, or else to distinct files
+on each of the processors, a special grammar has been designed,
+which is based on the '%' escape character. Four such escape
+sequences are defined, which are interpreted independently on every
+processor, prior to file opening. By default, when a filename is
+provided, it is assumed that the file is to be opened on only one of
+the processors, called the root processor, which is usually process
+0 of the communicator within which the program is run. The index
+of the root processor can be changed by means of the \fB-r\fP
+option. Using any of the first three escape sequences below will
+instruct programs to open in parallel a file of name equal to the
+interpreted filename, on every processor on which they are run.
+.TP
+.B
+%p
+Replaced by the number of processes in the global communicator in
+which the program is run. Leads to parallel opening.
+.TP
+.B
+%r
+Replaced on each process running the program by the rank of this
+process in the global communicator. Leads to parallel opening.
+.TP
+.B
+%-
+Discarded, but leads to parallel opening. This sequence is mainly
+used to instruct programs to open on every processor a file of
+identical name. The opened files can be, according whether the
+given path leads to a shared directory or to directories that
+are local to each processor, either to the opening of multiple
+instances of the same file, or to the opening of distinct files
+which may each have a different content, respectively (but in
+this latter case it is much recommended to identify files by
+means of the '%r' sequence).
+.TP
+.B
+%%
+Replaced by a single '%' character. File names using this escape
+sequence are not considered for parallel opening, unless one or
+several of the three other escape sequences are also present.
+.RE
+.PP
+For instance, filename 'brol' will lead to the opening of file 'brol'
+on the root processor only, filename '%\fB-brol\fP' (or even 'br%\fB-ol\fP') will
+lead to the parallel opening of files called 'brol' on every
+processor, and filename 'brol%p-%r' will lead to the opening of
+files 'brol2-0' and 'brol2-1', respectively, on each of the two processors
+on which the program were to run.
+.SH OPTIONS
+.TP
+.B
+\fB-c\fP
+For \fBdggath\fP and \fBdgscat\fP only. Check the consistency of the
+input source graph after loading it into memory.
+.TP
+.B
+\fB-h\fP
+Display some help.
+.TP
+.B
+\fB-r\fP\fIpnum\fP
+Set root process for centralized files (default is 0).
+.TP
+.B
+\fB-V\fP
+Display program version and copyright.
+.SH EXAMPLE
+Run \fBdgscat\fP on 5 processing elements to scatter centralized graph
+file brol.grf into 5 gzipped file fragments brol5-0.dgr.gz to
+brol5-4.dgr.gz.
+.PP
+.nf
+.fam C
+    $ mpirun -np 5 dgscat brol.grf brol%p-%r.dgr.gz
+
+.fam T
+.fi
+.SH SEE ALSO
+\fBdgmap\fP(1), \fBdgord\fP(1), \fBdgtst\fP(1), \fBgmk_hy\fP(1).
+.PP
+PT-Scotch user's manual.
+.SH AUTHOR
+Francois Pellegrini <francois.pellegrini at labri.fr>
diff --git a/debian/rules b/debian/rules
index 09eea91..72ce0c7 100755
--- a/debian/rules
+++ b/debian/rules
@@ -149,6 +149,8 @@ install: build
 #	Fix lintian missing man pages
 	cp debian/scotch_binaries.1 int/share/man/man1
 	cp debian/ptscotch_esmumps.1 int/share/man/man1
+	cp debian/dgscat.1 int/share/man/man1
+	cp debian/dgscat.1 int/share/man/man1/gscat.1
 #	Fix lintian warnings
 	for file in $(shell ls int/bin) scotch_binaries; do \
 	   (cd int/share/man/man1 && gzip -9n $$file.1); \
@@ -156,6 +158,7 @@ install: build
 	for file in scotch_esmumps scotch_gbase acpl amk_grf mcv; do \
 	   (cd int/share/man/man1 && ln -sf scotch_binaries.1.gz $$file.1.gz); \
 	done
+	cd int/share/man/man1 && ln -sf dgscat.1.gz dggath.1.gz
 	for file in $(shell ls int/bin); do \
 	   (cd int/share/man/man1 && ln -sf $$file.1.gz $$file-int32.1.gz); \
 	   (cd int/share/man/man1 && ln -sf $$file.1.gz $$file-int64.1.gz); \
@@ -172,6 +175,9 @@ clean:
 	for v in $(INTSIZE_VERS); do \
 	   (if [ -d $$v ]; then rm -rf $$v; fi); \
 	done
+	for file in scotch_binaries.1 ptscotch_esmumps.1 gscat.1; do \
+	   rm -f int/share/man/man1/$file; \
+	done
 	cp debian/Makefile.inc src/
 	make -C src/check realclean
 	make -C src realclean

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/debian-science/packages/scotch.git

