A proposal for the sectioning commangs

A proposal for the sectioning commangs

[Giuseppe Bilotta]

Hello,

one of the main features of both ConTeXt and LaTeX over plain TeX
is their heavily "object-oriented" approach to source writing,
giving a large set of useful tools to build well-structured
documents.

There is though one aspect which has not been addressed in either:
structuring of the sections. One still uses \chapter, \section,
\subsection etc to denote the start of any of these, while
structured writing would call for \startchapter ... \stopchapter,
\startsection ... \stopsection etc.

My proposal is to switch to such a method, while still retaining
compatibility with the old-style sectioning (maybe we can use some
flag like the one used to left left/right alignment use the
_correct_ term --what was the switch name?).

How should it work:

\startchapter[optional reference name]

Possible stuff before the title (e.g. an epigraph)

\title{Title of the chapter}
Optional commands to set alternative forms of the title (see
below)

Content

\stopchapter

Some pluses that would come from this approach, apart from
intrinsic structure:

* easy way to know where a section starts and ends (so as to be
able to put both starting and ending page in the ToC, for example).

* easy way to set different titles for ToCs, running heads, (PDF)
bookmarks etc. Consider the following hierarchy of titles:

title listtitle markingtitle bmtitle

Setting one of them would also set the subsequent ones (e.g.
setting the title would set all forms, setting the listtitle would
set the list, marking and bm title, but not the title). This is at
times needed because running heads usually need shorter texts, and
one cannot put special stuff (e.g. math) in bookmarks.
\title would also actually typeset the title. Note that none of
the commands \title, \listtitle, \markingtitle, \bmtitle should
write anything to the .tuo file; this ought to be done by the
\stop<section-name> command, which would save all of them together
with the appropriate counter values and beginning/ending page.

* easy way to put things before the title (e.g. an epigraph) while
still within the structure of the section.

* also comes from the above: currently, when using the /XYZ method
for PDF references, link targets end out-of-the-window because the
TeX cohordinate used is that of the baseline. This means that the
visible part of the page does not include the target reference
(which is rather uncomfortable). Instead, with the new approach
the mark could be set "right before everything else, but still
within the correct structure", with optimal PDF navigation.

* in editors that allow folding: proper folding of whole sections.

Hans, do you think you can implement this easily?

-- 
Giuseppe "Oblomov" Bilotta

Re: A proposal for the sectioning commangs

[John Culleton]

On Friday 21 June 2002 09:46 am, Giuseppe Bilotta wrote:
> Hello,
>
> one of the main features of both ConTeXt and LaTeX over plain TeX
> is their heavily "object-oriented" approach to source writing,
> giving a large set of useful tools to build well-structured
> documents.
>
> There is though one aspect which has not been addressed in either:
> structuring of the sections. One still uses \chapter, \section,
> \subsection etc to denote the start of any of these, while
> structured writing would call for \startchapter ... \stopchapter,
> \startsection ... \stopsection etc.
>
In my very humble opinion this is a big part of the problem with tools
such as XML and its children. Using two tags where one will do is just
excessive clutter, and ends up with lines like
\stopsubusubsection \stopsubsection \stopsection \stopchapter
.... which is all superfluous code and offers the chance for keying errors on 
every tag.  The computer is smart enough to know that a \chapter head 
terminates all previous subordinate levels. And the person reading the code 
is smart enough too. I see no virtue in this proposal. 

No matter how elegant the code looks, in fact it is just a means to an end, 
and the end is a publication, and all those meaningless stop tabs won't
afffect the final document in any case. 

Just my 2 centavos.

John Culleton
(programming since 1968, and it shows.)

__________________________________________________
D O T E A S Y - "Join the web hosting revolution!"
             http://www.doteasy.com

Re: A proposal for the sectioning commands--addendum

[John Culleton]

On Friday 21 June 2002 09:46 am, Giuseppe Bilotta wrote:
> Hello,
>

> * in editors that allow folding: proper folding of whole sections.
>
> Hans, do you think you can implement this easily?
Addendum to my previous comments:

I use folding in GVim by putting a ``stop'' command just before each 
``start'' commnad. this is clumsy but it is easier to remember than what 
Bilotti proposes. Better would be an editor that did this kind of controlling
automatically. Here is a sample of what I must do currently:

%--1
\chapter{The Best of Breed Software Packages}
%++1
%--2
\section{Operating Systems}
%++2
%--3
\subsection{Linux}
%++3

The above is not elegant but with the proper setup in .vimrc it works. 

I perhaps need to create a Vim macro that would put the befores and afters
on the tags. (e.g. %--2 before and %++2 after)

Incidentally I use Context not because it is ``structured'' but because it 
implements features not found in other incarnations of TeX, like hanging
punctuation and sidebars.

John Culleton

__________________________________________________
D O T E A S Y - "Join the web hosting revolution!"
             http://www.doteasy.com

Re[2]: A proposal for the sectioning commangs

[Giuseppe Bilotta]

Friday, June 21, 2002 John Culleton wrote:

JC> In my very humble opinion this is a big part of the problem with tools
JC> such as XML and its children. Using two tags where one will do is just
JC> excessive clutter, and ends up with lines like
JC> \stopsubusubsection \stopsubsection \stopsection \stopchapter
JC> .... which is all superfluous code and offers the chance for keying errors on 
JC> every tag.  The computer is smart enough to know that a \chapter head 
JC> terminates all previous subordinate levels. And the person reading the code 
JC> is smart enough too. I see no virtue in this proposal. 

I thought I pointed out some of the pluses ... do you have any
specific idea to counter to any of the pluses (apart from the
folding thingie which is just a bonus)?

JC> No matter how elegant the code looks, in fact it is just a means to an end, 
JC> and the end is a publication, and all those meaningless stop tabs won't
JC> afffect the final document in any case. 

Actually it does, in those cases when you want to do something at
the END of all section blocks of the same type (e.g. a local ToC)
--just put the appropriate code in the \stop<sectionblock> hook.
Other aspects of how my idea CAN affect the final result of the
document is provided in my original post.

-- 
Giuseppe "Oblomov" Bilotta

Re[2]: A proposal for the sectioning commands--addendum

[Giuseppe Bilotta]

Friday, June 21, 2002 John Culleton wrote:

>> Hans, do you think you can implement this easily?
JC> Addendum to my previous comments:

JC> I use folding in GVim by putting a ``stop'' command just before each 
JC> ``start'' commnad. this is clumsy but it is easier to remember than what 
JC> Bilotti proposes. Better would be an editor that did this kind of controlling
JC> automatically. Here is a sample of what I must do currently:

JC> %--1
JC> \chapter{The Best of Breed Software Packages}
JC> %++1
JC> %--2
JC> \section{Operating Systems}
JC> %++2
JC> %--3
JC> \subsection{Linux}
JC> %++3

JC> The above is not elegant but with the proper setup in .vimrc it works.

Since you can put up a Vim folding file that recognizes \start ...
\stop pair (and it would work with ANY \start ... \stop pair), you
can see how it helps. But of course the ability to fold easily is
just one (and the least important) of the pluses that come from
structured sectioning ..

JC> Incidentally I use Context not because it is ``structured'' but because it
JC> implements features not found in other incarnations of TeX, like hanging
JC> punctuation and sidebars.

So do I. But I also want to take advantage as much as possible of
the capabilities offered by the structure.

-- 
Giuseppe "Oblomov" Bilotta

Re: A proposal for the sectioning commangs

[Duncan Hothersall]

> The computer is smart enough to know that a
> \chapter head terminates all previous subordinate levels. And the
> person reading the code is smart enough too. I see no virtue in this
> proposal.

Consider a section which contains some content, followed by a subsection, 
followed by more content in the same section. I would tend to set this with 
vertical space indicating the end of the subsection. Without an explicit  
\stop the additional content of the section could belong either to the 
section or the subsection.

For me it isn't a problem, because I master in XML and create ConTeXt code 
from the XML using OmniMark. But for those using ConTeXt as a master format 
it must be quite important.

dh

Re: A proposal for the sectioning commangs

[John Culleton]

On Friday 21 June 2002 06:37 pm, Duncan Hothersall wrote:
> > The computer is smart enough to know that a
> > \chapter head terminates all previous subordinate levels. And the
> > person reading the code is smart enough too. I see no virtue in this
> > proposal.
>
> Consider a section which contains some content, followed by a subsection,
> followed by more content in the same section. I would tend to set this with
> vertical space indicating the end of the subsection. Without an explicit
> \stop the additional content of the section could belong either to the
> section or the subsection.
>
> For me it isn't a problem, because I master in XML and create ConTeXt code
> from the XML using OmniMark. But for those using ConTeXt as a master format
> it must be quite important.
>
> dh

I have never seen the kind of confuguration you describe. It is possible
I suppose. In general if my \section is subdvided it is completely subdivided.
Or there might be some introductory text right after the \section header and 
before the first \subsection header.  But returning to the same section after
a subsection would be difficult to configure. How would you indicate this
to a reader?  would you put in an additional header line such as 
``Section 22 (continued)''? Or are you using indentation for each level
of subdivision?

Perhaps you could give an example of how it would appear to the reader.
After all the mumbo jumbo one ends up with a document (either paper
or electronic) that some human being has to interpet and make some sense of. 
A section with a subsection embedded in the middle of its text would be 
difficult indeed to interpet.
John Culleton

__________________________________________________
D O T E A S Y - "Join the web hosting revolution!"
             http://www.doteasy.com

Re: A proposal for the sectioning commangs

[Hans Hagen]

At 03:46 PM 6/21/2002 +0200, Giuseppe Bilotta wrote:

>one of the main features of both ConTeXt and LaTeX over plain TeX
>is their heavily "object-oriented" approach to source writing,
>giving a large set of useful tools to build well-structured
>documents.
>
>There is though one aspect which has not been addressed in either:
>structuring of the sections. One still uses \chapter, \section,
>\subsection etc to denote the start of any of these, while
>structured writing would call for \startchapter ... \stopchapter,
>\startsection ... \stopsection etc.
>
>My proposal is to switch to such a method, while still retaining
>compatibility with the old-style sectioning (maybe we can use some
>flag like the one used to left left/right alignment use the
>_correct_ term --what was the switch name?).

actually, this is on my to do list, for most of the project that we run 
currently we use this approach since it gives you the options

(1) to skip a chapter / section
(2) to attach hooks to the end-of-some-section

>How should it work:
>
>\startchapter[optional reference name]
>
>Possible stuff before the title (e.g. an epigraph)
>
>\title{Title of the chapter}
>Optional commands to set alternative forms of the title (see
>below)

no, just \startchapter[ref]{title} is ok, since i don't want to pick up the 
title separately (imagine that you want \startchapter to trigger a complex 
title page

also, we currently test (play with) some mechanism to have section (or 
whatever) dependent variables, thereby introducing more convenient ways to 
tune typo behaviour.

* easy way to set different titles for ToCs, running heads, (PDF)
>bookmarks etc. Consider the following hierarchy of titles:
>
>title listtitle markingtitle bmtitle

that's for variables (since here we also have things like several graphics 
to be used in typesetting the chapter page)

>write anything to the .tuo file; this ought to be done by the
>\stop<section-name> command, which would save all of them together
>with the appropriate counter values and beginning/ending page.

hm, i'm not sure if i like that

>* easy way to put things before the title (e.g. an epigraph) while
>still within the structure of the section.
>
>* also comes from the above: currently, when using the /XYZ method
>for PDF references, link targets end out-of-the-window because the
>TeX cohordinate used is that of the baseline. This means that the
>visible part of the page does not include the target reference
>(which is rather uncomfortable). Instead, with the new approach
>the mark could be set "right before everything else, but still
>within the correct structure", with optimal PDF navigation.

that is a whole different matter, (1) output format/driver dependent and 
(2) can handled now by moving things around and (3) we don't want those 
funny nodes to screw up the spacing [actually, since i never use that xyz 
way of viewing docs [too inconstent auto scaling in viewers] i never felt 
the need to look into it; maybe something for a cold winter night]

>Hans, do you think you can implement this easily?

the \start-\stop thing will certainly be there

Hans
-------------------------------------------------------------------------
                                   Hans Hagen | PRAGMA ADE | pragma@wxs.nl
                       Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
  tel: +31 (0)38 477 53 69 | fax: +31 (0)38 477 53 74 | www.pragma-ade.com
-------------------------------------------------------------------------
                        information: http://www.pragma-ade.com/roadmap.pdf
                     documentation: http://www.pragma-ade.com/showcase.pdf
-------------------------------------------------------------------------

Re: A proposal for the sectioning commangs

[Hans Hagen]

At 11:27 AM 6/21/2002 -0400, John Culleton wrote:
>On Friday 21 June 2002 09:46 am, Giuseppe Bilotta wrote:
> > Hello,
> >
> > one of the main features of both ConTeXt and LaTeX over plain TeX
> > is their heavily "object-oriented" approach to source writing,
> > giving a large set of useful tools to build well-structured
> > documents.
> >
> > There is though one aspect which has not been addressed in either:
> > structuring of the sections. One still uses \chapter, \section,
> > \subsection etc to denote the start of any of these, while
> > structured writing would call for \startchapter ... \stopchapter,
> > \startsection ... \stopsection etc.
> >
>In my very humble opinion this is a big part of the problem with tools
>such as XML and its children. Using two tags where one will do is just
>excessive clutter, and ends up with lines like
>\stopsubusubsection \stopsubsection \stopsection \stopchapter
>.... which is all superfluous code and offers the chance for keying errors on
>every tag.  The computer is smart enough to know that a \chapter head
>terminates all previous subordinate levels. And the person reading the code
>is smart enough too. I see no virtue in this proposal.
>
>No matter how elegant the code looks, in fact it is just a means to an end,
>and the end is a publication, and all those meaningless stop tabs won't
>afffect the final document in any case.

a \start/stop option would be an extension, not a replacement, so you can 
still code minimal;

also, the stop thing is really needed for more complex layouts since we 
need trigger points

Hans
-------------------------------------------------------------------------
                                   Hans Hagen | PRAGMA ADE | pragma@wxs.nl
                       Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
  tel: +31 (0)38 477 53 69 | fax: +31 (0)38 477 53 74 | www.pragma-ade.com
-------------------------------------------------------------------------
                        information: http://www.pragma-ade.com/roadmap.pdf
                     documentation: http://www.pragma-ade.com/showcase.pdf
-------------------------------------------------------------------------

Re: A proposal for the sectioning commands--addendum

[Hans Hagen]

At 12:01 PM 6/21/2002 -0400, John Culleton wrote:

> > * in editors that allow folding: proper folding of whole sections.
> >
> > Hans, do you think you can implement this easily?
>Addendum to my previous comments:
>
>I use folding in GVim by putting a ``stop'' command just before each
>``start'' commnad. this is clumsy but it is easier to remember than what
>Bilotti proposes. Better would be an editor that did this kind of controlling
>automatically. Here is a sample of what I must do currently:
>
>%--1
>\chapter{The Best of Breed Software Packages}
>%++1
>%--2
>\section{Operating Systems}
>%++2
>%--3
>\subsection{Linux}
>%++3
>
>The above is not elegant but with the proper setup in .vimrc it works.
>
>I perhaps need to create a Vim macro that would put the befores and afters
>on the tags. (e.g. %--2 before and %++2 after)
>
>Incidentally I use Context not because it is ``structured'' but because it
>implements features not found in other incarnations of TeX, like hanging
>punctuation and sidebars.

right from the start the context syntax has been influenced and has 
influenced the way we edit texts; here we use texedit which we wrote long 
ago (in modula 2); due to some problems under win2k (the os2 mem model is 
no longer supported so we cannot run sub jobs) we've rewritten this editor 
in perl/tk. We're now in the process of switching. Since this editor is 
under my control, i can tune it a bit to context and vise versa. Structure 
based navigation is part of the game.

Hans
-------------------------------------------------------------------------
                                   Hans Hagen | PRAGMA ADE | pragma@wxs.nl
                       Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
  tel: +31 (0)38 477 53 69 | fax: +31 (0)38 477 53 74 | www.pragma-ade.com
-------------------------------------------------------------------------
                        information: http://www.pragma-ade.com/roadmap.pdf
                     documentation: http://www.pragma-ade.com/showcase.pdf
-------------------------------------------------------------------------

Re[2]: A proposal for the sectioning commands--addendum

[Giuseppe Bilotta]

Sunday, June 23, 2002 Hans Hagen wrote:

HH> right from the start the context syntax has been influenced and has 
HH> influenced the way we edit texts; here we use texedit which we wrote long 
HH> ago (in modula 2); due to some problems under win2k (the os2 mem model is 
HH> no longer supported so we cannot run sub jobs) we've rewritten this editor 
HH> in perl/tk. We're now in the process of switching. Since this editor is 
HH> under my control, i can tune it a bit to context and vise versa. Structure 
HH> based navigation is part of the game.

Any chance to have a look at it outside PRAGMA?

-- 
Giuseppe "Oblomov" Bilotta

Re[2]: A proposal for the sectioning commangs

[Hans Hagen]

At 11:15 PM 6/21/2002 +0200, you wrote:

>Actually it does, in those cases when you want to do something at
>the END of all section blocks of the same type (e.g. a local ToC)
>--just put the appropriate code in the \stop<sectionblock> hook.
>Other aspects of how my idea CAN affect the final result of the
>document is provided in my original post.

[another example is swiching fonts for a specific section, in which case 
you need grouping hooks]

for the same reason we need \startitem .. \stopitem

Hans
-------------------------------------------------------------------------
                                   Hans Hagen | PRAGMA ADE | pragma@wxs.nl
                       Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
  tel: +31 (0)38 477 53 69 | fax: +31 (0)38 477 53 74 | www.pragma-ade.com
-------------------------------------------------------------------------
                        information: http://www.pragma-ade.com/roadmap.pdf
                     documentation: http://www.pragma-ade.com/showcase.pdf
-------------------------------------------------------------------------

Re[2]: A proposal for the sectioning commands--addendum

[Hans Hagen]

At 11:42 PM 6/23/2002 +0200, Giuseppe Bilotta wrote:

>Sunday, June 23, 2002 Hans Hagen wrote:
>
>HH> right from the start the context syntax has been influenced and has
>HH> influenced the way we edit texts; here we use texedit which we wrote long
>HH> ago (in modula 2); due to some problems under win2k (the os2 mem model is
>HH> no longer supported so we cannot run sub jobs) we've rewritten this 
>editor
>HH> in perl/tk. We're now in the process of switching. Since this editor is
>HH> under my control, i can tune it a bit to context and vise versa. 
>Structure
>HH> based navigation is part of the game.
>
>Any chance to have a look at it outside PRAGMA?

in a couple of weeks it will go into the distribution, after we've catched 
a few bugs

Hans

-------------------------------------------------------------------------
                                   Hans Hagen | PRAGMA ADE | pragma@wxs.nl
                       Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
  tel: +31 (0)38 477 53 69 | fax: +31 (0)38 477 53 74 | www.pragma-ade.com
-------------------------------------------------------------------------
                        information: http://www.pragma-ade.com/roadmap.pdf
                     documentation: http://www.pragma-ade.com/showcase.pdf
-------------------------------------------------------------------------

Re[3]: A proposal for the sectioning commands--addendum

[Giuseppe Bilotta]

Monday, June 24, 2002 Hans Hagen wrote:

>>Any chance to have a look at it outside PRAGMA?

HH> in a couple of weeks it will go into the distribution, after we've catched 
HH> a few bugs

Yoohoo!

-- 
Giuseppe "Oblomov" Bilotta

texedit (was: something else)

[Henning Hraban Ramm]

Am Montag, 24. Juni 2002 10:55 schrieb Giuseppe Bilotta:
> HH> in a couple of weeks it will go into the distribution
> Yoohoo!

I agree! :-)
But I'd suggest to use an other name (texworks?) -- Texedit is a programmer's 
editor for MacOS that has nothing to do with TeX, but with Texas...

Grüßlis vom Hraban!
-- 
http://www.fiee.net/texnique/
---

Re: texedit (was: something else)

[Hans Hagen]

At 08:06 PM 6/24/2002 +0200, Henning Hraban Ramm wrote:
>Am Montag, 24. Juni 2002 10:55 schrieb Giuseppe Bilotta:
> > HH> in a couple of weeks it will go into the distribution
> > Yoohoo!
>
>I agree! :-)
>But I'd suggest to use an other name (texworks?) -- Texedit is a programmer's
>editor for MacOS that has nothing to do with TeX, but with Texas...

the tex editing env is called 'texwork'

the xml editing framework (lib under construction) is named 'example'

there is also texform (used for structured tex jobs based on templates) 
used for a long time internally

then there are codhost (web based publishing) and codwatch (server based 
texing) being tested now
-------------------------------------------------------------------------
                                   Hans Hagen | PRAGMA ADE | pragma@wxs.nl
                       Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
  tel: +31 (0)38 477 53 69 | fax: +31 (0)38 477 53 74 | www.pragma-ade.com
-------------------------------------------------------------------------
                        information: http://www.pragma-ade.com/roadmap.pdf
                     documentation: http://www.pragma-ade.com/showcase.pdf
-------------------------------------------------------------------------

Re: texedit (was: something else)

[Henning Hraban Ramm]

Am Dienstag, 25. Juni 2002 17:47 schrieb Hans Hagen:
> >But I'd suggest to use an other name (texworks?) -- Texedit is a
> > programmer's editor for MacOS that has nothing to do with TeX, but with
> > Texas...
> the tex editing env is called 'texwork'

Yes, but isn't the editor part of this environment?

> the xml editing framework (lib under construction) is named 'example'
> there is also texform (used for structured tex jobs based on templates)
> used for a long time internally
> then there are codhost (web based publishing) and codwatch (server based
> texing) being tested now

Do you have a own "project tool"? (Part of the IDE?)
I love my simple "makeproject.pl" for preparing new 
components/products/projects/environments, but I guess a tool of yours would 
be much more sophisticated...

Grüßlis vom Hraban!
(Who is just working on his second and third book with ConTeXt...)
-- 
http://www.fiee.net/texnique/
---

Re: texedit (was: something else)

[Hans Hagen]

At 08:43 PM 6/26/2002 +0200, you wrote:
>Am Dienstag, 25. Juni 2002 17:47 schrieb Hans Hagen:
> > >But I'd suggest to use an other name (texworks?) -- Texedit is a
> > > programmer's editor for MacOS that has nothing to do with TeX, but with
> > > Texas...
> > the tex editing env is called 'texwork'
>
>Yes, but isn't the editor part of this environment?

it is

> > the xml editing framework (lib under construction) is named 'example'
> > there is also texform (used for structured tex jobs based on templates)
> > used for a long time internally
> > then there are codhost (web based publishing) and codwatch (server based
> > texing) being tested now
>
>Do you have a own "project tool"? (Part of the IDE?)
>I love my simple "makeproject.pl" for preparing new
>components/products/projects/environments, but I guess a tool of yours would
>be much more sophisticated...

hm, sounds like a nice option;

but, as with our current editor, texwork *is* aware of the structure and 
permits you to traverse subfiles.

Hans

-------------------------------------------------------------------------
                                   Hans Hagen | PRAGMA ADE | pragma@wxs.nl
                       Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
  tel: +31 (0)38 477 53 69 | fax: +31 (0)38 477 53 74 | www.pragma-ade.com
-------------------------------------------------------------------------
                        information: http://www.pragma-ade.com/roadmap.pdf
                     documentation: http://www.pragma-ade.com/showcase.pdf
-------------------------------------------------------------------------

Re: texedit (was: something else)

[Henning Hraban Ramm]

[-- Attachment #1: Type: text/plain, Size: 713 bytes --]

Am Donnerstag, 27. Juni 2002 18:54 schrieb Hans Hagen:
> >Do you have a own "project tool"? (Part of the IDE?)
> >I love my simple "makeproject.pl" for preparing new
> >components/products/projects/environments, but I guess a tool of yours
> > would be much more sophisticated...
>
> hm, sounds like a nice option;
> but, as with our current editor, texwork *is* aware of the structure and
> permits you to traverse subfiles.

Sounds good.
I guess, your editor can create "every" ConTeXt structure from the menu or 
shortcut? That would replace the attached script... (Hey, I never claimed to 
be a Perl hacker, just a bloody beginner!)

Grüßlis vom Hraban!
-- 
http://www.fiee.net/texnique/
---

[-- Attachment #2: makeproject.pl --]
[-- Type: text/x-perl, Size: 6643 bytes --]

#!/usr/bin/perl -w
use warnings;
print "Make ConTeXt project -- 2002-05-17\n";
print "copyleft 2002 Henning Hraban Ramm\n\n";

@Level       = ("environment","project", "product","component");
@Prefix      = ("env_",       "project_","prd_",   "c_");	# file prefixes
$Suffix      = ".tex";				# ending
$IniSuffix   = ".ini";				# ending for defaults files

$Command     = $ARGV[0];
if (!$Command) {$Command=".";}
$validCommand = 0;
$ProjectPath = ".";	# default path = actual path


if ($Command =~ m/^--/) { 		# if first parameter starts with --
	$Command =~ s/^--//; 		# delete --
	($Command eq "help") && help();	# show help, if wanted
	if ($Command =~ m/[0-3]/) { $Command = $Level[$Command]; } # if --0 etc.
	for ($count=@Level-1; $count>0; $count--) { # iterate all levels
		if ($Command eq $Level[$count]) { # if command matches level
			unless ($ARGV[1]) { # if no second command line parameter
				my $missname = $Level[$count-1];
				if ($missname eq $Level[0]) { $missname = $Level[1]; }
				help("$missname name is missing!");
			} # if no second parameter
			if (($count>1) and (!$ARGV[2])) { # with level 2 we need 2 parameters
				help($Level[$count]." name is missing!");
			} # if no third parameter
			$validCommand=1;	# ok, print no help
			print "making ".$Level[$count]."...\n";
			MakeFile($count, $ARGV[1], $ARGV[2]);
		} # if
	} # for
	($Command eq "all") && help("option --all is not yet implemented.\n");
	($validCommand) && exit(0); # exit without error
} # if --parameter

help("Don't know what to do!");	# help function ends with exit

### END

###
sub MakeFile { # gets level number and two other args (project/product or product/component)
###
	my $ActLev = $_[0];
	my $ProjectName=$_[1];
	my $ProductName=$_[2];
	my $InKey="";
	my $ProjectLine="";
	if ($ProjectName =~ m/^.*[\/\\:]/) { # look for folder delimiters
		$ProjectName = $';	# '
		chop($ProjectPath = $&);
		$ProjectPath =~ tr§\:\/\\§/§;	# change all delimiters to UNIX slashes
	} # if
	if (ProductName =~ m/^.*[\/\\:]/) { # delete other path
		$ProductName = $';	# '
	}
	if (!$ProductName) { $ProductName=$ProjectName; }
	unless (-d $ProjectPath) { # test path
		(-f $ProjectPath) && die "$ProjectPath is a file!\n";
		print("making $ProjectPath...");
		mkdir($ProjectPath) or die "Cannot make dir $ProjectPath: $!";
	} # if no path
	$FileName = $ProjectPath."/".$Prefix[$ActLev].$ProductName.$Suffix;
	(-d $FileName) && die "$FileName is a directory!\n";

# Insert entry in next level file
	($ActLev == 1) && MakeFile(0,$ProjectPath."/".$ProjectName,$ProductName); # project makes environment
	if ($ActLev > 1) { # insert product and component into next level
		my @FileList = ();
		my $Count = 0;
		$ProjectFileName = $ProjectPath."/".$Prefix[$ActLev-1].$ProjectName.$Suffix;
		print "Inserting ".$Prefix[$ActLev].$ProductName." into ".$Level[$ActLev-1]." ".$ProjectFileName."...\n";
		open (myFILE, $ProjectFileName) or warn "Cannot open $ProjectFileName: $!";
		while (<myFILE>) {
			$FileList[$Count] = $_;
			if (($ActLev==3) && (m/\\project/)) { # if component
				$ProjectLine = $_;
			} # if component and project line in product file
			if (m/\\stop$Level[$ActLev-1]/) { $StopPos = $Count; }
			if (m/$Prefix[$ActLev]$ProductName/) {
				$Exist = 1;
				print "Entry exists already.\n";
			}
			$Count++;
		} # while myFILE
		close (myFILE);
		if (!$Exist) {
			open (myFILE, ">".$ProjectFileName) or warn "Cannot open $ProjectFileName: $!";
			for ($Count=0; $Count < @FileList; $Count++) {
				if ($Count == $StopPos) {
					print myFILE "\t\\".$Level[$ActLev]." ".$Prefix[$ActLev].$ProductName."\n";
				} # if StopPos
				print myFILE $FileList[$Count];
			} # for
			close (myFILE);
		}
	} # insert product and component into next level

# Make this level file
	if (-f $FileName) {
		print "$FileName exists. May I overwrite it? (YJ/N, Return)\n";
		while ($InKey !~ m/[JYN]/i) {
			$InKey= "";
			print "?";
			$InKey = getc;
		} # while
	} # if file exists
	$IniFile = $Level[$ActLev].$IniSuffix; # defaults for every level

	if ($InKey !~ m/N/i) {
		print "Making $FileName...\n";
		open (myFILE, ">".$FileName) or die "Cannot make $FileName: $!";

		($ActLev == 1) && print myFILE "% output=pdf interface=en\n";
		print myFILE "\\start".$Level[$ActLev]." ".$Prefix[$ActLev].$ProductName."\n";
		if (!$ActLev) { $tempLev=1; } else { $tempLev=$ActLev-1; }
		print myFILE "\\$Level[$tempLev] ".$Prefix[$tempLev].$ProjectName."\n";
		($ProjectLine) && print myFILE $ProjectLine;
		print myFILE "\n";
		if ($ActLev==1) {
			print myFILE "%  \\showlayout\n";
			print myFILE "%  \\showgrid\n";
			print myFILE "%  \\showbodyfontenvironment\n";
		} # if project
		if (-T $IniFile) { # look for .ini file in script dir
			open (iniFILE, $IniFile) or warn "Cannot open $IniFile: $!";
			print "inserting $IniFile into $FileName...\n";
			while (<iniFILE>) { print myFILE;} # while
			close (iniFILE) or warn "Cannot close $IniFile: $!";
		}
		$IniFile = $ProjectPath."/".$IniFile;
		if ((-T $IniFile) && ($ProjectPath ne ".")) { # look for .ini file in project dir
			open (iniFILE, $IniFile) or warn "Cannot open $IniFile: $!";
			print "inserting $IniFile into $FileName...\n";
			while (<iniFILE>) { print myFILE;} # while
			close (iniFILE) or warn "Cannot close $IniFile: $!";
		}
		print myFILE "\n";
		print myFILE "\\stop$Level[$ActLev]\n";
		print myFILE "\n";

		close (myFILE) or die "Cannot close $FileName: $!";

	} # if InKey not N

} # sub MakeFile



###
sub help {
###
	($_[0]) && print "ERROR: $_[0]\n\n";
	print "Syntax: makeproject --help\n";
	print "        will give this help\n";
	print "......: makeproject --project <projectname>\n";
	print "        will make $Prefix[1]<projectname>$Suffix and $Prefix[0]<projectname>$Suffix\n";
	print "......: makeproject --product <projectname> <productname>\n";
	print "        will make $Prefix[2]<productname>$Suffix and add it to $Prefix[1]<projectname>$Suffix\n";
	print "......: makeproject --component <productname> <componentname>\n";
	print "        will make $Prefix[3]<componentname>$Suffix and add it to $Prefix[2]<productname>$Suffix\n";
#	print "......: makeproject --all <productname>\n";
#	print "        will make all of the files, asks after names\n";
	print "Path should be only in first name!\n";
	exit(1);
} # sub help