[tei-council] Editing the Guidelines

[Rebecca Welzenbach]

Thanks, Martin.

The bulleted list of steps at
http://www.tei-c.org/Activities/Council/Working/tcw20.xml#body.1_div.4
reads as though "Make sure your source is still valid against the
p5odds.rnc schema," is its own step, to be completed before either
doing a local build or committing to let Jenkins assess the changes.

Martin did indeed come up with a way to do this (which works just
fine, BTW!). However, the text that follows in
http://www.tei-c.org/Activities/Council/Working/tcw20.xml#body.1_div.4
gives lots of reasons for letting Jenkins do all the validation for
you, which suggests to me that validating against p5odds.rnc was never
really meant to be attempted by those who are choosing the
commit-and-wait option.

If that's right, instead of expanding this step, I suggest that the
sentence "Make sure your source is still valid against the p5odds.rnc
schema," either just be dropped altogether, or become part of the
bullet underneath, "If you have a locally installed P5 build
environment, make sure you can still build, and that the examples are
still valid," so that it's clear this is part of the process of
checking your work with a local build, but can be safely ignored if
you're just going to commit and wait for results from Jenkins.


Becky






On Tue, May 15, 2012 at 12:13 PM, Martin Holmes <mholmes at uvic.ca> wrote:
> Hi all,
>
> Becky has pointed out what looks like a slight flaw in the "Editing the
> Guidelines" document:
>
> <http://www.tei-c.org/Activities/Council/Working/tcw20.xml>
>
> It says this:
>
> "Make your changes. Make sure your source is still valid against the
> p5odds.rnc schema."
>
> p5odds.rnc is not in the repo, of course; it's generated during a build.
> That means that you don't have a copy of that file unless you do a
> build. In order to do a build, you need a range of stuff set up on your
> machine (for instance, you need the TEI Debian packages if you're on
> Ubuntu, otherwise "make" will fail as soon as it hits an "rnv" command;
> rnv doesn't appear to be in the Ubuntu repos any more, if it ever was).
> I don't know what happens if you're on a Mac or Windows, or what you'd
> need to install to get a build working.
>
> What I suggested to Becky is that she validate any changes to the
> Guidelines in a two-stage process, like this:
>
> 1. Create a fully-expanded version of the guidelines by doing this in
> /trunk/P5/Source:
>
>   xmllint --noent guidelines-en.xml -o guidelines-en_expanded.xml
>
> 2. Open that file in Oxygen, and do Document/Validate/Validate with...
> then point to the latest p5odds.rnc file generated by a Jenkins build:
>
> <http://teijenkins.hcmc.uvic.ca:8080/job/TEIP5-Test/ws/p5odds.rng>
>
> This is a bit onerous, and for most minor changes you might as well just
> let Jenkins do the job. It also requires that you have xmllint
> installed, but that's less problematic than what you need for a full build.
>
> Does that seem reasonable, or is there a simpler approach?
>
> Cheers,
> Martin
> --
> Martin Holmes
> University of Victoria Humanities Computing and Media Centre
> (mholmes at uvic.ca)
> --
> tei-council mailing list
> tei-council at lists.village.Virginia.EDU
> http://lists.village.Virginia.EDU/mailman/listinfo/tei-council
>
> PLEASE NOTE: postings to this list are publicly archived