Quickbok 1.5

Templates

Dynamic Scoping vs. Static Scoping

quickbook currently uses dynamic scoping which is generally accepted to be a bad idea. So I'd like to change it to use static scoping.

   [template x static scoping]
   [template foo1[] [x]]
   [template foo2[x] [foo1]]
   [foo2 dynamic scoping]

Will currently return 'dynamic scoping', I'd like it to change it to return 'static scoping' for 1.5 or whatever.

Template Lookup Location

#2034

When template arguments are expanded they are evaluated with the current scope rather than the scope they were called with which can be surprising. So I'd like to change it so that they are bound to the correct scope.

  [template x new]
  [template foo1[a x] [a]]
  [foo1 [x] old]

Will return 'old' at the moment, I'd prefer it to return 'new'. Another way to achieve this would be to evaluate template arguments eagerly but that would be a much bigger change and harder to implement a version switch for.

Simplified Template Arg Handling

#1174

David Abrahams wrote:

IMO the rules that allow you to do things like leave out a nullary template's argument list when the template body doesn't look like an argument list

Joel:

This can be removed. I agree.

David:

and combining simple argument separators with ".." separators are confusing at best and don't provide real utility. I think we should avoid such syntax quirks.

Joel:

Those are there to provide backward compatibility. One of the goals is to replace/rewrite most of the rules using templates. Alas, QB's syntax is admittedly quirky to begin with. In an ideal world, I'd redesign the syntax set and rewrite Qb, but, I guess I don't quite have time to invest on such a rewrite.

David:

I also have no problem with

[stuff a..b..c..d]

I do have a problem with

[stuff a..b c d]

unless that's just 2 arguments.

Joel:

Alright, so you want it either to be the first form, or the second form, but not combined. Noted.

Brackets in template arguments

#2036

[template join1[a b] [b][a]] [/<- "error: Expanding template"]
[template join2[a b] [a][b]]
[template test[x] [join1 [join2 0 [x]] 0]]
[test 0]

The problem here is that join1 is interpreting spaces as argument seperators. So this line:

[template test[x] [join1 [join2 0 [x]] 0]]

join is interpreted as having the arguments

[join2

and

0 [x]] 0

which is confusing. It should be interpreted as having the arguments

[join2 0 [x]]

and

0

I think that both seperators (spaces and ..) should be ignored inside square brackets. So this means that

[join1 [join2 0 [x]] 0]
[join1 [join2 0 [x]]..0]
[join1 [join2 0..[x]] 0]
[join1 [join2 0..[x]]..0]

Would all be equivalent.

Images

Image Attributes

#1157

Give images attributes using the notation:

[$image_path
    [format ...] [width ...] [srccredit ...] [contentdepth ...] [contentwidth ...]
    [scalefit ...] [align ...] [valign ...] [depth ...] [scale ...]
]

An example from my tests:

    [$test.gif [width 10cm] [height 10cm]]

This also supports a HTML style 'alt' attribute:

    [$ball.gif [alt A ball]]

which generates docbook along the lines of:

<inlinemediaobject>
    <imageobject><imagedata fileref="test.gif"></imagedata></imageobject>
    <textobject><phrase>A ball</phrase></textobject>
</inlinemediaobject>

Although, this still doesn't support everything that docbook supports, for example in the Math documentation different images are used for print and html:

[template graph[name]  '''<inlinemediaobject>
<imageobject role="html">
<imagedata align="center" fileref="../graphs/'''[name]'''.png"></imagedata>
</imageobject>
<imageobject role="print">
<imagedata align="center" fileref="../graphs/'''[name]'''.svg"></imagedata>
</imageobject>
</inlinemediaobject>''']

Tables

Table Ids

#1194 ​http://www.nabble.com/Quickbook-table-bug--to6604943.html

This allows you to explicity give a table an id so that it's easier to link to:

[table:table1 Table 1
    [[Heading]]
    [[cell]]
]

Sections

Ignoring spaces after 'section:'

In this example:

[section: example Example section]

Quickbook would consider the section to not have an id, and use the title 'example Example section'. In 1.5 documents the id would be 'example', and the title 'Example section' which I think is less confusing.

This lead to some confusion in #2712.