axiom-developer
[Top][All Lists]

## [Axiom-developer] Re: Tex(t) chunk inclusion and citation

 From: root Subject: [Axiom-developer] Re: Tex(t) chunk inclusion and citation Date: Fri, 6 Dec 2002 23:11:43 -0500

> Tim wrote:
>
> > Further, I need two behaviors for text chunks.
> >
> > First, I need to be able to essentially \include a text chunk from
> > another document (or maybe a whole text root) into the current
> > document. This is to ensure that information that is widely needed is
> > not copied everywhere (otherwise some copies will be out of date).
> >
> > I also need this ability in order to construct "booklets" without
> > copying the original sources but also without including the original
> > sources in total as \include would do. Think of a booklet as a thread
> > thru pamphlets with text along the threads. This will allow one to
> > write a chapter introduction, include some text and code chunks from
> > some pamphlet, and then write a summary or problems section (for a
> > textbook).
>
> Obvious problems:
>
>
> This would be especially delicate when the text chunk produces source
> that would be published, say, not within the open-source or Axiom
> journal, but outside these.

Well, first I've obtained permission for the various documents I'm
using (though motivated more by respect for the author than the legal
issue). Second, most of the quoted text will come from other pamphlets.
Third, publication outside of Axiom raises the issue of BSD licensing
of text of which I have no opinion as I've come to understand that Law
is at least as complex as programming and only experts should play.
Fourth, in the spirit of science it seems that the whole benefit is to
been a huge benefit to the original authors (in my experience) as they
end up signing away those rights just to get published anyway. Sixth,
the subject is so complex that one can only depend on the cooperation
of the members of the community. Seventh, if some event DOES cause a
problem the only reasonable response is to withdraw the text and
apologize. Eighth, a large portion of this work is done by people
around the world so it raises the issue of international copyrights,
an even more arcane subject. Ninth, there seems to be great advantage
to having your Axiom-related research work distributed with Axiom and
that IS the point of publishing, right?

Unless we get a few lawyers on this mailing list who have qualified
opinions I don't see the point of discussing the legal issues. Yes,
I know it is important but without some authoritative opinion we're
subject of intellectual property, been advised by a lawyer over
intellectual property issues related to employment and read the
debates on open-free-proprietary. My only conclusion is that we have
to leave this subject to the people with law degrees.

So all I can suggest is: ask permission then proceed.

> (2) technical.
>
> There has to be some very restrictive convention on text chunks that is
> TeX/LaTeX source (and similarly for other types of source that supports
> any macros). For example, if within a text chunk, \renewcommand\xxx{...}
> is allowed, then when other text chunks are assembled, the assembler
> will need to be smart enough to save the the current definition of xxx
> before getting into that chunk and restore it afterwards -- but this may
> create problems too, because the original intention of the chunk author
> may be that \renewcommand\xxx{...} has a larger scope than the text
> chunk. The problem does not exist for the author, because the author
> knows and presumably verify the assembled output. But when the text
> chunk is \include(d) by other authors, it will be like calling a
> subroutine with global variables reset as side-effect. Other commands
> involving defining any macro are equally problematic.
>
> One solution may be to limit the scope of macros local to the text
> chunk, if the text chunk is intended for reuse. But how does the text
> assembler know the previous environment without being the TeX compiler?
> (Perhaps there is a TeX command to query the definitions of a particular
> macro? I am no TeX/LaTeX expert, but as we will see, this facility will
> be very useful. Let's call this the macroResolver for now. Such a
> program is not too difficult to write for TeX gurus.)
>
> How would code chunk assemblers solve this problem? In Axiom, we are
> allowed to define macros (say, textual string substitutions with ==>,
> not to mention the == ). So again we need an equivalent macrResolver.

Yes, this would be a problem. However, you can change any of the
pamphlets or booklets and submit the changes to CVS. Thus, it is
possible to dance around the issue by changing the referred-to
document to eliminate the problem. It does raise the issue of

> > Second, I need to \cite a text chunk in a woven document. Then I
> > can cross-reference the documents so a reader mechanism can follow
> > the citations. This comes from pondering ideas of how to read the
> > .dvi files in some rational way. I'm tempted to automatically
> > construct an html tree on top of the dvi files but I'm not happy
> > with this solution for the long term.
>
> Citation can presumably be done by creating a protocol that identifies
> the location of the source. So the problem is defining what "location"
> is, perhaps in a similar way to URL. But there is more. You are not
> contemplating on just citing a DOCUMENT, but a TEXT CHUNK, that is the
> equivalent of chapter and verse citation. So each citable text chunk
> must have its own "URL" (let say we call it UCL, for chunk locator). If
> you are using .dvi as the source (because you want to avoid compiling
> the source again), you will need to embed the UCL info into the .dvi
> source, which requires modifying TeX (not an elegant solution). The html
> tree construct would work for entire DOCUMENT citation because the
> entire .dvi file is retrieved and displayed. The user must then manually
> scroll to find the right place. Not every .dvi (or .ps) viewer supports
> searching. A .pdf version would be easier as far as the user goes since
> (a) we don't have to maintain Acrobat Reader (b) it has good searching
> facilities.

The process generates:

pamphlet -> tex -> dvi

I expect that the "source" will be the pamphlet file.
In some instances it might need to be the tex file but we should
probably figure out clever ways to avoid this. The dvi file (or
ps or pdf or html or whatever final target gets chosen) is a
"compiled" form. However, TeXmacs could probably do some fancy
things with almost any level assuming someone is willing to write
the code.

...(snip)...

> So I leave you with an open problem, and readers of booklets will still
> have to scroll and search manually the meaning of symbols.
>
> We can severely restrict how a citable chunk or reference can be written
> -- they need be self-contained.

Hopefully the final "reader" (quite possibly TeXmacs or some other new
open source tool) will handle the problems you raise. I've been pondering
them for a while but don't have any grand insights to share. It's all in
the requirements-gathering phase, of which you've raised a few, at the
moment.

Tim