File: examples_sharing.html

package info (click to toggle)
funnelweb-doc 3.2d-5
links: PTS, VCS
area: main
in suites: forky, sid
size: 3,740 kB
sloc: perl: 241; makefile: 23
file content (267 lines) | stat: -rw-r--r-- 9,267 bytes
parent folder | download | duplicates (6)

<HTML>
<!--
***********************************************************************
FUNNELWEB MANUAL WEB PAGE
=========================
Copyright (c) Ross N. Williams 1992,1999. All rights reserved.

Permission is granted to redistribute and use this manual in
any medium, with or without modification, provided that all
notices (including, without limitation, the copyright
notice, this permission notice, any record of modification,
and all legal notices) are preserved on all copies, that all
modifications are clearly marked, and that modified versions
are not represented as the original version unless all the
modifications since the manual's original release by Ross N.
Williams (www.ross.net) consist of translations or other
transformations that alter only the manual's form, not its
content. THIS MANUAL IS PROVIDED "AS IS" AND WITHOUT ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
FITNESS FOR A PARTICULAR PURPOSE. TO THE EXTENT PERMITTED BY
LAW THERE IS ABSOLUTELY NO WARRANTY.

***********************************************************************
-->

<HEAD>
<TITLE>6.6 Documents That Share Text</TITLE>
<STYLE TYPE="text/css"> <!-- A {text-decoration: none} // --> </STYLE>
</HEAD>
<BODY BACKGROUND="binary/background.gif"
      BGCOLOR="#FFFFFF"
      TEXT="#000000"
      VLINK="#660000"
      LINK="#FF0000"
      ALINK="#CC0000">

<TABLE WIDTH="490">
<TR>
<TD WIDTH="130" VALIGN="top">
<IMG SRC="binary/d_clear.gif" ALT="" WIDTH="130" HEIGHT="1"><BR>

<FONT SIZE="2">
<BR>

<A HREF="http://www.ross.net/"
 TARGET="rosshome"
 onClick="window.open('','rosshome','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
 <IMG SRC="binary/rossnet_logo.gif"
  WIDTH="64" HEIGHT="32"
  BORDER="0" ALT="RossNet"
  HSPACE="0" VSPACE="1"></A><BR>
<BR>

<A HREF="../index.shtml"
 TARGET="funnelweb"
 onClick="window.open('','funnelweb','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
>
 <IMG SRC="binary/linklogo.gif"
  WIDTH="64" HEIGHT="32"
  BORDER="0" ALT="FunnelWeb"
  HSPACE="0" VSPACE="1"></A><BR>
<BR>
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0><TR><TD BGCOLOR="#000000">
<A HREF="../reference/index.html"
 TARGET="funnelwebreference"
 onClick="window.open('','funnelwebreference','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Reference</B></FONT></A><BR>
<BR>
<A HREF="../developer/index.html"
 TARGET="funnelwebdeveloper"
 onClick="window.open('','funnelwebdeveloper','location,status,menubar,scrollbars,resizable',false).focus(); return true;"
><FONT COLOR="#FFFFFF"><B>Developer</B></FONT></A><BR>
<BR>
<A HREF="index.html"><FONT COLOR="#FFFFFF"><B>Tutorial</B></FONT></A><BR>
<A HREF="intro.html"><FONT COLOR="#FFFFFF">1 Introduction</FONT></A><BR>
<A HREF="macro.html"><FONT COLOR="#FFFFFF">2 Macros</FONT></A><BR>
<A HREF="type.html"><FONT COLOR="#FFFFFF">3 Typesetting</FONT></A><BR>
<A HREF="example.html"><FONT COLOR="#FFFFFF">4 Example</FONT></A><BR>
<A HREF="hints.html"><FONT COLOR="#FFFFFF">5 Hints</FONT></A><BR>
<A HREF="examples.html"><FONT COLOR="#FFFFFF">6 Examples</FONT></A><BR>
<A HREF="web.html"><FONT COLOR="#FFFFFF">7 Webmaking</FONT></A><BR>

<BR>
<A HREF="search.html"><FONT COLOR="#FFFFFF"><B>SEARCH</B></FONT></A><BR>
</FONT>
</TD></TR></TABLE>


</TD>
<TD WIDTH="360" VALIGN="top">
<FONT SIZE="3">


<A HREF="../reference/index.html"><IMG SRC="binary/title.gif"
 WIDTH="302" HEIGHT="24"
 BORDER="0" ALT="FunnelWeb Tutorial Manual"
 HSPACE="0" VSPACE="0"></A>
<P><FONT SIZE="5">6.6 Documents That Share Text</FONT><BR>



<P>FunnelWeb is very useful when preparing multiple
documents that must share large slabs of identical text that
are being constantly modified.

<P>For example someone preparing two slightly different
user manuals for two slightly different audiences might want
the manuals to share large slabs of text, while still
allowing differences between them. The following example
shows how this can be done. The code is cluttered, but this
clutter would not be a problem if the lumps of text were
moderately large.

<P>
<PRE>
@O@&lt;manual1.txt@&gt;==@{@&lt;M1@&gt;@+@}
@O@&lt;manual2.txt@&gt;==@{@&lt;M2@&gt;@+@}

@$@&lt;M1@&gt;+=@{@&lt;T1@&gt;@}
@$@&lt;M2@&gt;+=@{@&lt;T1@&gt;@}
@$@&lt;T1@&gt;@M==@{@-
First lump of text shared by both documents.@+@}

@$@&lt;M1@&gt;+=@{Text for first document@+@}
@$@&lt;M2@&gt;+=@{Text for second document@+@}

@$@&lt;M1@&gt;+=@{@&lt;T2@&gt;@}
@$@&lt;M2@&gt;+=@{@&lt;T2@&gt;@}
@$@&lt;T2@&gt;@M==@{@-
Second lump of text shared by both documents.@+@}
</PRE>

<P>An alternative approach, which might work better in
situations where there are many small differences between
the two documents rather than a few large ones, is to define
a macro with two arguments, one for each product file
document. Write the document from top to bottom, but place
all stretches that differ between the two documents in a
macro call.

<P>
<PRE>
@! Set the definition of @#D to
@!    @1 to create the shareholders report.
@!    @2 to create the customers report.
@$@#D@(@2@)@M==@{@1@}

@O@&lt;report.txt@&gt;==@{@-
ANNUAL REPORT TO @#D@(Shareholders@,Customers@)
=================@#D@(============@,=========@)
This has been a very good year for The Very Big
Corporation of America. With your help, we have
been able to successfully
@#D@(@"screw the customers
          for every cent they have@"@,
     @"knock the shareholders into
        submission to bring you lower prices@"@).
With gross earnings approaching six trillion
dollars, we have been able to
@#D@(@"increase dividends@"@,
     @"lower prices@"@).
We expect to have an even better year next year.
@}
</PRE>

<P>One application where text sharing can be particularly
useful is in the preparation of computer
documentation containing
examples. For example, a book describing a new programming
language might be full of examples of small programs written
in the language which the user might want to try without
having to type them all in. The "default" approach
of keeping a copy of the examples in the text of the book
and another copy in separate files is cumbersome and error
prone, because both files have to be updated whenever an
example is changed. A more sophisticated approach is to
store each example in a separate file, and then use the
"include file" facility of the word processor to
include each example in the text. This is a better solution,
but suffers from a few drawbacks. First, when editing the
book in a word processor, the examples in the book will not
be directly accessible or visible. To see an example, the
writer would have to open the file containing the example in
a separate window. This could become tedious if the text
contained many examples, as many texts do. Furthermore,
there is a risk that some example files will be included in
the wrong place. Second, because the book is dependent on
the included files, the book will end up consisting of a
directory of a hundred or more files instead of just a few.

<P>An alternative solution is to construct a single
FunnelWeb <SAMP>.fw</SAMP> file that, when processed, produces
both the book file and the example files. This solution
assumes that the book consists of a text file containing
commands for a typesetter such as TeX.

<PRE>
@O@&lt;Book.tex@&gt;==@{@#B@}

@$@#B+=@{@-
The first step to learning the object oriented
AdaCgol++ language is to examine a hello world
program.

\start{verbatim}
@&lt;Ex1@&gt;
\finish{verbatim}
@}

@$@&lt;Ex1@&gt;==@{@-
read iopack@+Enter !World~! !Hello~! ex pr flu X[1]@}
@O@&lt;Ex1.c@&gt;==@{@&lt;Ex1@&gt;@}

@$@#B+=@{@-
To understand the program, think of the execution
state as a plate of cheese...
@}
</PRE>

<P>Most of the file will consist of part
definitions of the additive macro <SAMP>@#B</SAMP>.
The definition is "broken" to allow a
macro definition, wherever an example appears.

<P>The example above is a little messy because
FunnelWeb does not allow macros connected to
product files to be called, and it does not have
text expressions that write to an product file as
well as evaluating to text. Nevertheless, it
presents a fairly clean solution to the problem of
keeping the example programs in a computing text
up to date.


<P>
<TABLE WIDTH="100%">
<TR>
<TD ALIGN="left"   VALIGN="bottom"><A HREF="examples_comments.html"><IMG SRC="binary/fw_left.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Prev"></A></TD>
<TD ALIGN="center" VALIGN="bottom"><A HREF="examples.html"><IMG SRC="binary/fw_up.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Up"></A></TD>
<TD ALIGN="right"  VALIGN="bottom"><A HREF="examples_generics.html"><IMG SRC="binary/fw_right.gif" HEIGHT="32" WIDTH="32" BORDER="0" ALT="Next"></A></TD>
</TR>
</TABLE>



<HR>
<FONT SIZE="2">
<A HREF="mailto:webmaster@ross.net">Webmaster</A>&nbsp;&nbsp;&nbsp;
<A HREF="copyright.html">Copyright &copy; Ross N. Williams 1992,1999. All rights reserved.</A><BR>
</FONT>

</FONT>
</TD>
</TR>
</TABLE>


</BODY>

<!-- *********************************************************************** -->
<!--      End Of A FunnelWeb Manual Web Page (www.ross.net/funnelweb/)       -->
<!-- *********************************************************************** -->

</HTML>