[Pmwiki-users] Re: [[include: ... ]] part of a page

[Patrick R. Michaud]

I now have a preliminary implementation for [[include: ... ]]
part of a page running on pmichaud.com, and invite people to test
it.  I have a test page set up at

   http://www.pmichaud.com/wiki/Test/IncludeTest

I followed the basics of Christian's recommendation but made a few
slight modifications/additions.  The generic syntax is

   [[include:SomePage#anchor1#anchor2]]

which includes the portion of SomePage starting with the markup line
containing [[#anchor1]] up to but not including the markup line containing
[[#anchor2]].  If "anchor1" isn't specified or doesn't exist in SomePage,
then the included portion starts from the beginning of SomePage; likewise,
if "anchor2" isn't specified or doesn't exist in SomePage, then the
included portion extends to the end of SomePage.  Thus, we get:

   [[include:SomePage]]          - include all of SomePage
   [[include:SomePage#from#to]]  - include lines between #from and #to
   [[include:SomePage#from#]]    - include everything after #from
   [[include:SomePage##to]]      - include everything before #to

For now, as a special case, [[include:SomePage#from]] includes only
the markup line containing the [[#from]] anchor, although we may wish
to change this to be something a bit larger, such as a "paragraph" (up to
the next blank line) or a "section" (up to the next anchor).  An open
question is what should happen with [[include:SomePage#from]] 
if [[#from]] doesn't exist in SomePage-- should nothing be included?  
(I believe my current implementation includes the entire page, but I
think my vote would be to include nothing in this case.)

In addition, since HTML doesn't allow anchor names to begin with 
a digit, I've overloaded the syntax to use numbers as "pseudo-anchors" 
representing line numbers in the markup of included file.  Thus, the 
following work:

   [[include:SomePage##5]]       - include the first 5 lines of SomePage
   [[include:SomePage#5#]]       - include everything after the first 5 lines
   [[include:SomePage#5#20]]     - include lines 6-20 of SomePage

This may work for people wanting to excerpt RecentChanges -- i.e., one
can do [[include:RecentChanges##10]] to display only the ten most 
recent changes.

I still haven't settled on useful meanings for

   [[include:SomePage#]]
   [[include:SomePage##]]

and so I've left them undefined at the moment.  Christian's suggestion to use
[[include:SomePage#]] to mean "include the first paragraph" sounds pretty
handy, but it's not entirely clear what constitutes a paragraph in this
case.  We could have it be just the first markup line, but that's not 
really necessary since someone can now do [[include:SomePage##1]] for that.
So it would likely be either "everything to the first blank line", or 
"everything to the first anchor".  I'm open for discussion on this point,
and will leave this part of the implementation undefined until we've had
a chance to better understand what we've built thus far.  :-)

Comments and tests greatly encouraged (use the Test group on pmwiki.org).  
If I see enough tests with no major bugs or issues then I'll release 
this as an update within the next 24 hours.

Pm