[groff] 01/02: gideal: include files/; restructure man-pages

[Bernd Warken]

bwarken pushed a commit to branch master
in repository groff.

commit d028727a678026e26871b72ce3f9c0d40713b97c
Author: Bernd Warken <address@hidden>
Date:   Wed Jun 18 23:00:15 2014 +0200

    gideal: include files/; restructure man-pages
---
 contrib/gideal/ChangeLog                 |   22 +++
 contrib/gideal/Makefile.sub              |   23 ++-
 contrib/gideal/files/README.txt          |    5 +
 contrib/gideal/files/opaque_MIT.ideal.ms |  252 ++++++++++++++++++++++++++++++
 contrib/gideal/files/test.groff          |   13 ++
 contrib/gideal/gideal.man                |  120 +++++++++++++--
 contrib/gideal/gideal.pl                 |    6 +-
 contrib/gideal/ideal.man                 |   79 ++++++++--
 8 files changed, 486 insertions(+), 34 deletions(-)

diff --git a/contrib/gideal/ChangeLog b/contrib/gideal/ChangeLog
index 21d7e39..7b5d3b7 100644
--- a/contrib/gideal/ChangeLog
+++ b/contrib/gideal/ChangeLog
@@ -1,3 +1,25 @@
+2014-06-18  Bernd Warken  <address@hidden>
+
+       New version 0.9.2
+
+       * gideal.pl: The preproc will transform the `ideal' parts into
+       `pic'.
+
+       * gideal.man, ideal.man: Restructure the `SEE ALSO' part.  Include
+       also the installed location with address@hidden@' variables.
+
+       * files/: New directory with example files with `ideal parts'.
+
+       * Makefile.sub: Install `files/' (into @DATASUBDIR@) and improve
+       `libfiles/' (into @EXAMPLEDIR@).
+
+2014-06-17  Bernd Warken  <address@hidden>
+
+       * gideal.pl: New version 0.9.1.
+
+       * libfiles/: New directory for `ideal' inclusion files.  They will
+       be implemented in `roff' files with the ideal command `libfiles'.
+
 2014-06-16  Bernd Warken  <address@hidden>
 
        * Project: Project `gideal' with starting version 0.9 without real
diff --git a/contrib/gideal/Makefile.sub b/contrib/gideal/Makefile.sub
index df5029d..02a4654 100644
--- a/contrib/gideal/Makefile.sub
+++ b/contrib/gideal/Makefile.sub
@@ -46,26 +46,35 @@ gideal: gideal.pl
            $(srcdir)/gideal.pl >$@; \
        chmod +x $@
 
-.PHONY: libdirs
-libdires: 
-
 .PHONY: install_data
 install_data: gideal
        -test -d $(DESTDIR)$(bindir) || $(mkinstalldirs) $(DESTDIR)$(bindir)
        $(RM) $(DESTDIR)$(bindir)/gideal
        $(INSTALL_SCRIPT) gideal $(DESTDIR)$(bindir)/gideal
+
+       -test -d $(DESTDIR)$(datasubdir) \
+          || $(mkinstalldirs) $(DESTDIR)$(datasubdir)
        -test -d $(DESTDIR)$(datasubdir)/ideal \
           || $(mkinstalldirs) $(DESTDIR)$(datasubdir)/ideal
        -test -d $(DESTDIR)$(datasubdir)/ideal/libfiles \
           || $(mkinstalldirs) $(DESTDIR)$(datasubdir)/ideal/libfiles
        $(RM) $(DESTDIR)$(datasubdir)/ideal/libfiles/*
-       for i in $(srcdir)/libfiles/*.ideal; do \
+       for i in $(srcdir)/libfiles/*; do \
          n=`echo $$i | sed 's|$(srcdir)/libfiles/||g'`; \
          $(INSTALL_DATA) $$i $(DESTDIR)$(datasubdir)/ideal/libfiles/$$n; \
        done
-       $(RM) $(DESTDIR)$(datasubdir)/ideal/libfiles/README.txt
-       $(INSTALL_DATA) $(srcdir)/libfiles/README.txt \
-               $(DESTDIR)$(datasubdir)/ideal/libfiles/README.txt;
+
+       -test -d $(DESTDIR)$(exampledir) \
+          || $(mkinstalldirs) $(DESTDIR)$(exampledir)
+       -test -d $(DESTDIR)$(exampledir)/ideal \
+          || $(mkinstalldirs) $(DESTDIR)$(exampledir)/ideal
+       -test -d $(DESTDIR)$(exampledir)/ideal/files \
+          || $(mkinstalldirs) $(DESTDIR)$(exampledir)/ideal/files
+       $(RM) $(DESTDIR)$(exampledir)/ideal/files/*
+       for i in $(srcdir)/files/*; do \
+         n=`echo $$i | sed 's|$(srcdir)/files/||g'`; \
+         $(INSTALL_DATA) $$i $(DESTDIR)$(exampledir)/ideal/files/$$n; \
+       done
 
 
 .PHONY: uninstall_sub
diff --git a/contrib/gideal/files/README.txt b/contrib/gideal/files/README.txt
new file mode 100644
index 0000000..36e64dc
--- /dev/null
+++ b/contrib/gideal/files/README.txt
@@ -0,0 +1,5 @@
+opaque_MIT.ideal.ms:
+       http://web.mit.edu/usrdoc/ditroff/ideal.man/opaque
+
+test.groff:
+       easy short file with `ideal parts'
diff --git a/contrib/gideal/files/opaque_MIT.ideal.ms 
b/contrib/gideal/files/opaque_MIT.ideal.ms
new file mode 100644
index 0000000..45dd389
--- /dev/null
+++ b/contrib/gideal/files/opaque_MIT.ideal.ms
@@ -0,0 +1,252 @@
+.NH 1
+Opaque Boxes
+.PP
+\*(id includes statements to blot out pieces
+of a picture.
+In this section we will sometimes place opaque boxes
+without explicitly drawing any background.
+In such cases, assume
+that we have painted over
+the area with pens as above.
+.NH 2
+Opaque Polygons
+.PP
+\*(id needs to know the vertices of a polygon in order
+to opaque the area it covers.
+The vertices are specified as a list in a
+.IT bdlist
+statement.
+For instance, to opaque a rectangular region using the
+.IT rect
+box defined in Section 3, we could use the following statement:
+.IS
+...libfile rect
+wavy {
+       var start, end, perp, pt1, pt2, ht;
+       perp = (0,1)*(start - end)/abs(start - end);
+       pt1 = 0.25[start,end] + perp*ht;
+       pt2 = 0.75[start,end] - perp*ht;
+       conn start to pt1 to pt2 to end;
+}
+brush {
+       var top, bot;
+       var bwd, bht;
+       var leftpt, rightpt;
+       leftpt = 0.5*(top+bot) - bwd/2;
+       rightpt = 0.5*(top+bot) +bwd/2;
+       conn leftpt to rightpt
+               using 7 wavy {
+                       ht = bht;
+               }<start,end>;
+}
+background {
+       conn (0,1) to (0,-1)
+               using 7 brush {
+                       bwd = 2;
+                       bht = 0.1;
+                       }<top,bot>;
+}
+main {
+       put background {
+       };
+       put rect {
+               opaque;
+               bdlist = sw, se, ne, nw;
+               sw = (-0.4,-0.4);
+               wd = ht = 1;
+       };
+}
+.IF
+.P1
+put rect {
+       opaque;
+       bdlist = sw, se, ne, nw;
+       sw = (-0.4,-0.4);
+       wd = ht = 1;
+};
+
+
+
+
+.P2
+.LP
+The sides of the rectangle are drawn by
+.IT rect :
+they are not supplied automatically by the opaqueing routine.
+If we wanted to save only the interior of the rectangle,
+we could use almost the same statement:
+.IS
+...minx -1.0
+...maxx 1.0
+...miny -1.0
+...maxy 1.0
+main {
+       put background {
+       };
+put rect {
+       opaque exterior;
+       bdlist = sw, se, ne, nw;
+       sw = (-0.4,-0.4);
+       wd = ht = 1;
+};
+}
+.IF
+.P1
+put rect {
+       opaque exterior;
+       bdlist = sw, se, ne, nw;
+       sw = (-0.4,-0.4);
+       wd = ht = 1;
+};
+.P2
+.PP
+If we plan to opaque a lot of rectangles,
+we should include a
+.IT bdlist
+in the definition of
+.IT rect .
+Such a default
+.IT bdlist
+would be referenced only if the parameter section
+of the put statement included an opaque statement
+.IT and
+did not include its own
+.IT bdlist .
+.NH 2
+Opaque Circular Arc Polygons
+.PP
+The edges of opaque regions can also be circular arcs.
+.Ts
+This generalization of the simple boundary statement
+is the most recent addition to \*(id.
+It avoids treating circles and their sectors and segments
+as special cases, and makes opaqueing circular
+arc polygons much easier.
+.Te
+.LP
+To specify a circular arc edge, one gives its endpoints
+and a point through which it passes;
+this ``pass-through'' point is marked in the boundary
+list by the symbol ``\f8^\fP''.
+For example, the boundary list for the sector shown below is
+.IS
+...libfile sector
+main {
+       put background {
+       };
+put sector {
+       center = (-1,-1);
+       radius = 2;
+       startang = 30;
+       endang = 60;
+       opaque;
+};
+}
+.IF
+.P1
+boundary = center, cis(30), ^ cis(45), cis(60);
+
+
+
+
+
+.P2
+.PP
+Another common opaque arc is the segment:
+.IS
+...libfile segment
+main {
+       put background {
+       };
+put segment {
+       center = (-1,-1);
+       radius = 2;
+       startang = 0;
+       endang = 90;
+       opaque;
+};
+}
+.IF
+.P1
+boundary = cis(0), ^ cis(45), cis(90);
+
+
+
+
+
+
+
+
+
+
+.P2
+.PP
+One can construct an opaque circle out of two semicircular edges:
+.IS
+...libfile circle
+main {
+       put background {
+       };
+put circle {
+       radius = 0.5;
+       center = 0;
+       opaque;
+};
+put circle {
+       radius = 1;
+       center = 0;
+       opaque exterior;
+};
+}
+.IF
+.P1
+boundary = cis(0), ^ cis(90), cis(180), ^ cis(270);
+
+
+
+
+
+
+.P2
+.LP
+Here, the outer circle has an opaque exterior,
+while the inner circle has an opaque interior.
+.NH 2
+Order is Important
+.PP
+Without the ability to opaque,
+the order in which boxes are put does not matter.
+But when some boxes are opaque, order obviously
+.IT does
+matter.
+Put statements are executed
+in the order in which they appear in the box definition.
+When an opaque box is drawn, the opaquing is done
+.IT first ,
+then the lines of the box are drawn;
+so, for instance, an opaque
+.IT listnode
+does include the line down its middle separating its
+.IT info
+field from its
+.IT next
+field.
+.NH 2
+Some Hard Facts
+.PP
+Neither text nor splines can be used to opaque objects,
+nor will they be clipped properly if they are in a
+picture and an opaque box is placed over them.
+.Ts
+The problem with text is that \*(id operates as a \*(tf preprocessor,
+so it cannot determine anything about the size of the
+text, and it needs to know that if it is to do anything
+involving opaquing and text.
+.Te
+.Ts
+The problem with splines is more subtle.
+When a line or circular arc is chopped,
+it is easy to specify the lines or circular arcs that remain.
+But when a spline is chopped, the guiding points of the resulting curve pieces
+are hard to determine.
+.Te
diff --git a/contrib/gideal/files/test.groff b/contrib/gideal/files/test.groff
new file mode 100644
index 0000000..74816b4
--- /dev/null
+++ b/contrib/gideal/files/test.groff
@@ -0,0 +1,13 @@
+.nf
+before
+.IS
+this is within
+the first ideal part
+.IE
+outside
+.IS
+the number
+is now 2
+.IF
+after
+.fi
\ No newline at end of file
diff --git a/contrib/gideal/gideal.man b/contrib/gideal/gideal.man
index 5badfc7..47a6c77 100644
--- a/contrib/gideal/gideal.man
+++ b/contrib/gideal/gideal.man
@@ -15,7 +15,7 @@ gideal.1 - man page for the ideal roff preprocessor
 Source file position:  <groff_source_top>/contrib/gideal/gideal.man
 Installed position:    $prefix/share/man/man1/gideal.1
 .
-Last update: 16 Jun 2014
+Last update: 18 Jun 2014
 ..
 .
 .de authors
@@ -59,14 +59,13 @@ The license text is available in the internet at
 .UE .
 ..
 .
-.
 .\" --------------------------------------------------------------------
 .\" Setup
 .\" --------------------------------------------------------------------
 .
+.char \[Ellipsis] \f[S]\N'188'\fP
 .\" ds Ellipsis "\&.\|.\|.\&\"
 .
-.
 .\" --------------------------------------------------------------------
 .\" Macro definitions
 .\" --------------------------------------------------------------------
@@ -261,22 +260,82 @@ or
 The text between these requests is handled by the preprocessor
 .BR gideal .
 .
+By that the
+.I ideal part
+is transformed into
+.IR "pic content" ,
+belonging to another graphical preprocessor
+.BR pic (1).
+.
 .
 .\" --------------------------------------------------------------------
 .SH HISTORY
 .\" --------------------------------------------------------------------
 .
-The roff preprocessor and the roff language
-.I ideal
-were invented by
+The roff language
+.BR ideal (@MAN7EXT@)
+was invented by
 .I Christopher J. Wyk
 in 1981 at AT&T.
 .
 .
+.P
+A roff preprocessor for this language with the same name was also
+invented by the same programmer, but this preprocessor is very
+old-fashioned.
+.
+That's why there is a completely new within groff is in the development.
+.
+It is called
+.BR gideal (@MAN1EXT@),
+other thatn the original preprocessor.
+.
+.
 .\" --------------------------------------------------------------------
 .SH "SEE ALSO"
 .\" --------------------------------------------------------------------
 .
+.\" --------------------------------------------------------------------
+.SS "libfiles"
+.\" --------------------------------------------------------------------
+.
+.I libfiles
+are files written in
+.IR ideal .
+.
+Such a file can be included into a roff file with
+.I ideal parts
+by the ideal command
+.BR ...libfile .
+.
+A
+.I libfile
+can also serve as an example.
+.
+.
+.P
+With the installation, the available
+.I libfiles
+get into
+.B @DATASUBDIR@/ideal/libfiles
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Examples"
+.\" --------------------------------------------------------------------
+.
+Some
+.I roff
+files with included 
+.Iideal parts
+will be stored at the installation into
+.BR @EXAMPLEDIR@/ideal .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Man-Pages"
+.\" --------------------------------------------------------------------
+.
 .TP
 .BR ideal (@MAN7EXT@)
 for information about the
@@ -286,6 +345,26 @@ in
 .
 .
 .TP
+.BR groff (@MAN1EXT@),
+.TQ
+.BR groff (@MAN7EXT@),
+.TQ
+.BR grog (@MAN1EXT@),
+.TQ
+.BR pic (@MAN1EXT@),
+.TQ
+.BR gpic (@MAN1EXT@),
+.TQ
+Information about the
+.I groff
+system.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Documentation and Articles"
+.\" --------------------------------------------------------------------
+.
+.TP
 .B Unix8 preprocessor
 freely available documentation for the
 .IR "ideal preprocessor" .
@@ -304,12 +383,29 @@ as in
 .
 .
 .TP
-.BR groff (@MAN1EXT@),
-.TQ
-.BR groff (@MAN7EXT@)
-Information about the
-.I groff
-system.
+.B ACM articles for buying
+.
+.RS
+.
+.TP
+.B p99-van_wyk.pdf.gz
+.nf
+A Graphics Typesetting Language
+Christopher J. Van Wyk
+.fi
+.UR http://dl.acm.org/citation.cfm?id=806460
+.UE
+.
+.TP
+.B p163-van_wyk.pdf.gz
+.nf
+A High-Level Language for Specifying Pictures
+Christopher J. Van Wyk
+.fi
+.UR http://dl.acm.org/citation.cfm?id=357303
+.UE
+.
+.RE
 .
 .
 .\" --------------------------------------------------------------------
diff --git a/contrib/gideal/gideal.pl b/contrib/gideal/gideal.pl
index a51b7bd..ef5d44a 100755
--- a/contrib/gideal/gideal.pl
+++ b/contrib/gideal/gideal.pl
@@ -10,8 +10,8 @@
 
 # Written by Bernd Warken <address@hidden>.
 
-my $Latest_Update = '16 Jun 2014';
-my $version = '0.9';
+my $Latest_Update = '17 Jun 2014';
+my $version = '0.9.1';
 
 # This file is part of `gideal', which is part of `groff'.
 
@@ -73,7 +73,7 @@ $| = 1;       # flush after each print or write command
 # read-only variables with double-@ construct
 ########################################################################
 
-my $before_make;        # script before run of `make'
+my $before_make;       # script before run of `make'
 {
   my $at = '@';
   $before_make = 1 if '@VERSION@' eq "${at}VERSION${at}";
diff --git a/contrib/gideal/ideal.man b/contrib/gideal/ideal.man
index 5b975ba..ec5b44a 100644
--- a/contrib/gideal/ideal.man
+++ b/contrib/gideal/ideal.man
@@ -198,14 +198,78 @@ bit about related Perl examles.
 .SH "SEE ALSO"
 .\" --------------------------------------------------------------------
 .
+.\" --------------------------------------------------------------------
+.SS "libfiles"
+.\" --------------------------------------------------------------------
+.
+.I libfiles
+are file written in
+.IR ideal .
+.
+Such a file can be included into a roff file with
+.I ideal parts
+by the ideal command
+.BR ...libfile .
+.
+A
+.I libfile
+can also serve as an example.
+.
+.
+.P
+With the installation, the available
+.I libfiles
+will get into
+.B @DATASUBDIR@/ideal/libfiles
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Examples"
+.\" --------------------------------------------------------------------
+.
+Some
+.I roff
+files with included 
+.I ideal parts
+will be stored at the installation into
+.BR @EXAMPLEDIR@/ideal .
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Man-Pages"
+.\" --------------------------------------------------------------------
+.
 .TP
 .BR gideal (@MAN1EXT@)
-for information about the corresponding groff preprocesor
+for information about the
+.I ideal
+preprocessor in
+.IR groff .
 .
 .
 .TP
+.BR groff (@MAN1EXT@),
+.TQ
+.BR groff (@MAN7EXT@),
+.TQ
+.BR grog (@MAN1EXT@),
+.TQ
+.BR pic (@MAN1EXT@),
+.TQ
+.BR gpic (@MAN1EXT@),
+.TQ
+Information about the
+.I groff
+system.
+.
+.
+.\" --------------------------------------------------------------------
+.SS "Documentation and Articles"
+.\" --------------------------------------------------------------------
+.
+.TP
 .B Unix8 preprocessor
-Freely available documentation for the
+freely available documentation for the
 .IR "ideal preprocessor" .
 .
 The
@@ -213,7 +277,7 @@ The
 there is called
 .BR ideal ,
 not
-.BR gideal (@MAN1EXT@)
+.B gideal
 as in
 .IR groff .
 .br
@@ -247,15 +311,6 @@ Christopher J. Van Wyk
 .RE
 .
 .
-.TP
-.BR groff (@MAN1EXT@),
-.TQ
-.BR groff (@MAN7EXT@)
-Information about the
-.I groff
-system.
-.
-.
 .\" --------------------------------------------------------------------
 .SH "AUTHORS"
 .\" --------------------------------------------------------------------