#512 Generate statistics in the Guidelines rather than hard code

AMBER
closed-fixed
nobody
5
2013-05-14
2013-01-23
James Cummings
No

At various places in the Guidelines, for example, http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ST.html#STECST there are statistics of number of elements using particular macros. It seems silly to have these manually hard coded in the text because we've probably not updated them in quite awhile, or may forget to do so in the future.

I'd recommend we change the Guidelines generation to either use <divGen> or <ptr> or something here to generate the table or their individual values.

Similarly we say in many places that the Guidelines contain 'around 500 elements', when the number of elements is easily countable when processing the guidelines.

In the same way we use <specDesc> in writing the Guidelines it seems silly to not have some mechanism to grab always changing details such as these.

I'm not proposing the correct mechanism to encode this in the Guidelines since that probably needs some discussion.

Discussion

  • you could easily use Guidelines-specific PIs for this. Just use them in the prose, and add an implementation to the guidelines processing XSL.

    I find it hard to see this as a general facility in ODD3, to be honest.

     
  • James Cummings
    James Cummings
    2013-01-23

    You're right, Guidelines-specific processing instructions are probably the way to go. But we need to decide what they should look like/work, do the XSLT, and make sure we test for them not being processed properly. I think it is probably fairly low priority, but does seem like something we should do someday.

     
  • James Cummings
    James Cummings
    2013-04-09

    • Group: --> AMBER
     
  • Kevin Hawkins
    Kevin Hawkins
    2013-04-12

    Council breakout group agrees that this is a good idea to fix but low priority. In the meantime, we suggest a manual revision of any known data points mentioned in the text (like the "500 elements").

     
  • Martin Holmes
    Martin Holmes
    2013-04-12

    Action on MH to write XSLT against the Specs to generate Table 3 in Ch 1, along with the para before it, as a file, and XInclude this into the Guidelines. The XSLT should be run as part of the make process.

     
  • Martin Holmes
    Martin Holmes
    2013-04-25

    Sebastian has set up a pre-processing stage for the compilation of the Guidelines XML source, prior to transformation into other products; this is in Utilities/expand.xsl. I have started adding processing instruction templates into that. The basic idea is that we have processing instructions in the source that look like this:

    <?insert totalElements?>

    and these are then matched in expand.xsl and expanded into the correct content. The list of these instructions will be documented in the style guide, and also explained and linked in the "How to edit the Guidelines" document.

     
  • Martin Holmes
    Martin Holmes
    2013-04-26

    The original ticket says "At various places in the Guidelines" there are stats etc. which could be automated. I've found two instances where I've been able to insert the total element count (one in USE and one in ST), and of course the table of macros I was tasked with generating, in the ST chapter. But I can't find any other instances of the sort of thing that would be better automated. There's a table of modules and their chapters in ST, but that will change so rarely that it seems pointless to slow the build process down by generating it.

    Can anyone point at other locations where this sort of automated content can be generated?

     
  • Martin Holmes
    Martin Holmes
    2013-04-26

    TCW 20 updated to document this practice and the current PIs in use.

     
  • Martin Holmes
    Martin Holmes
    2013-05-14

    I'm going to close this ticket since no further suggestions have come forward.

     
  • Martin Holmes
    Martin Holmes
    2013-05-14

    • status: open --> closed-fixed