[pmwiki-users] (:include parameters

[Martin Fick]

On Mon, Nov 21, 2005 at 02:41:38PM -0600, Patrick R. Michaud wrote:
> On Mon, Nov 21, 2005 at 03:29:20PM -0500, Martin Fick wrote:
> > On Mon, Nov 21, 2005 at 09:15:49AM -0600, Patrick R. Michaud wrote:
> > > (:include Page#from#to:) has always been defined in PmWiki as a
> > > line-oriented markup.  If we really want to cut markers in
+mid-line
> > > we probably need a different option or (:include:) syntax to
+support it.
> >
> >   While I can see the utility of the current markup, I find
> > myself using it more the way that Henrik wants to use it.
> >
> > I would suggest this added syntax:
> >
> >     (:include section=Section Page:)
> >
> > where Section is assumed to be two anchors such as:
> >
> >     [[#Section]]
> >
> >     ...and ...
> >
> >     [[#SectionEnd]]
> >
> > This would greatly reduce the wordiness for this case.
>
> Could you rephrase this as a more complete description?
> I.e., are you saying that we should change the existing #from#to
> markup in any way, or are you simply saying we should add a
> section= syntax so that someone can write "section=Section"
> instead of "#Section#SectionEnd"?

OK, well I was attacking of few things at once here, let me
see if I can slow things down (and maybe improve my
suggestions a little) :)

I see the following issues:

  1) (:include Page#Section1#Section2:)  always includes full lines

  2) (:include Page#Section#SectionEnd:)  can be a little wordy

  3)  includes with non-existing sections include the entire page.


I think that changing the way # 1 works (by default) would
break  things for a lot of people so I am not really
suggesting that.

a) One way would be to add a linemode=off parameter which would
   allow Henrik's example:

      Hello There. [[#Start]]This is the first sentence that I want to
      Include.[[#End]] And the rest I don't want.

   to work properly.

b) To make #2 prettier I suggest adding a new block=<blockname>
   option (I orginally said section=, but block= is yet even
   more concise) which would work similarly to the current

     (:include Page#Description#DescriptionEnd:)

   markup, but instead could be written as:

     (:include block=Description Page:)


c1) To deal with # 3, add a defaultblank=true option which
   would not include any text if a block did not exist.

c2) Instead of C1), add a default="default text" option
  which would print "default text" when a section does not
  exist.

  This would be more usefull as an author driven option,
  (true, I do think that of most things), than as a config
  option.  The reason: when designing PageListTemplates I
  think that authors could really use this flexibility.
  Many of the questions on this list have to do with
  syntaxes/formatting of things referencing other pages, it
  seems that people have a growing desire to do this.

  Since PageListTemplates always refers to other pages,
  giving the authors flexibilty in this area is particularly
  helpfull.  For example if a [[#Description]] block is
  blank, someone might want to put the page's title, or page
  name in place of the description.  This option would allow
  then to do that easily.



d) Since I feel that I mostly want to be able to use
  suggestions a) linmode=off and c1) defaulblank=true, I
  was suggesting making these the default behaviour for b)
  since it would be a new syntax and would not break
  anything for anyone.  Of course, if people think that
  this is more usefull in other cases also and that few
  people would be upset by such a change, then make it the
  default in all cases.

  Again, especially with PageListTemplates it is becoming
  more evident to me that people seem to want to be able to
  discriminate more accurately where the include starts and
  ends, particularly as to avoid including markup such as the
  !!!s in your example.  So making this behaviour the
  default for new cases makes sense to me while avoiding
  breaking the old case.

e) And not addressing #1, #2 or #3, but rather the previous
  paragraph, another extremely error prone option would be
  to add a start=<regexp> and an end=<regexps> option.
  These options would take a regular expression describing
  the text to include.  Sounds much better as a fringe
  recipe though. :)



  -Martin