OK, I’ve been working through the branch schema a bit to figure out
how to restructure it to be able to easily extract a spec. But before
going much farther, I guess I should ask: what should the spec look
like in the end?
Here’s an example that might be relevant from the Atom spec:
http://www.atomenabled.org/developers/syndication/atom-format-spec.php
Is this what we want?
If yes, it might make sense to consider a rather different approach
than we’ve so far taken with the schema: to use a literature
programming approach.
To do that, we’d author the spec in XML (probably XHTML or DocBook),
embed the schema fragments in the document, and then extract the
schema from the doc.
But I’m trying to find out more about that to avoid unnecessary extra work.
Also, what should be the sections headings be? My thought is something like:
introduction
style metadata
general structures
dates
names
macros
text
localized terms
flow control
sorting
contexts
citation
options
bibliography
options
Finally, who’s going to help with this?
Bruce
I think it would be a very good thing if
http://www.zotero.org/support/dev/csl_syntax_summary could be made redundant
by an easily readable spec, and I wouldn’t mind to help. DocBook seems to
have a nice range of output options, although it looks a bit unwieldy.
Rintze
I think it would be a very good thing if
dev:csl_syntax_summary [Zotero Documentation] could be made redundant
by an easily readable spec,
I think it’s probably worthwhile to have two documents: the spec (more
for developers) and a tutorial (like the one you note above).
and I wouldn’t mind to help. DocBook seems to
have a nice range of output options, although it looks a bit unwieldy.
Yeah, there are different options, and the right choice needs to be a
balance between ease-of-authoring and ease-of-publishing (in the form
that we want).
I did some more research, and Atom seems to have been patched together
via a pretty hairy process. But there is an XSLT stylesheet that can
take XML input (not DocBook, but similar) and create the HTML output
you see. I contacted the guy that wrote the stylesheet for his
thoughts.
Another option is using markdown for authoring and convert it to XHTML
and RNC. Only minor problem with that is pandoc doesn’t have RNC
syntax-highlghting, and I can’t find a kate syntax file for the
language.
Note, a markdown version of the start of the tutorial is in the SVN.
Feel free to add to that.
Bruce
I think it would be a very good thing if
dev:csl_syntax_summary [Zotero Documentation] could be made
redundant
by an easily readable spec,
I think it’s probably worthwhile to have two documents: the spec (more
for developers) and a tutorial (like the one you note above).
Note that the csl-syntax-summary page isn’t a tutorial (there isn’t one,
really, except for the recent effort of keesp:
http://www.condast.com/zotero/index.html), it’s a spec.
and I wouldn’t mind to help. DocBook seems to
have a nice range of output options, although it looks a bit unwieldy.
Yeah, there are different options, and the right choice needs to be a
balance between ease-of-authoring and ease-of-publishing (in the form
that we want).
I did some more research, and Atom seems to have been patched together
via a pretty hairy process. But there is an XSLT stylesheet that can
take XML input (not DocBook, but similar) and create the HTML output
you see. I contacted the guy that wrote the stylesheet for his
thoughts.
I came across this example of DocBook:
Another option is using markdown for authoring and convert it to XHTML
and RNC. Only minor problem with that is pandoc doesn’t have RNC
syntax-highlghting, and I can’t find a kate syntax file for the
language.
Note, a markdown version of the start of the tutorial is in the SVN.
Feel free to add to that.
markdown would seem much friendlier. I did find a reference to a RelaxNG
kate-file, but couldn’t find the link to the file itself:
http://archives.devshed.com/forums/kde-96/new-syntax-file-for-relax-ng-2259437.html
Rintze
Found it (Google came to the rescue):
Relevant bug report:
http://bugs.kde.org/show_bug.cgi?id=143931
Direct link:
http://bugsfiles.kde.org/attachment.cgi?id=20203
Seems to work exclusively for Relax NG XML though.
RintzeOn Sun, Jun 14, 2009 at 10:40 PM, Rintze Zelle <@Rintze_Zelle>wrote:
I think it would be a very good thing if
dev:csl_syntax_summary [Zotero Documentation] could be made
redundant
by an easily readable spec,
I think it’s probably worthwhile to have two documents: the spec (more
for developers) and a tutorial (like the one you note above).
Note that the csl-syntax-summary page isn’t a tutorial (there isn’t one,
really, except for the recent effort of keesp:
http://www.condast.com/zotero/index.html), it’s a spec.
Not exactly. I expect a spec to include fragments from the schema,
rather than examples from the XML instances. Bu you’re right; it’s not
so clear cut.
and I wouldn’t mind to help. DocBook seems to
have a nice range of output options, although it looks a bit unwieldy.
Yeah, there are different options, and the right choice needs to be a
balance between ease-of-authoring and ease-of-publishing (in the form
that we want).
I did some more research, and Atom seems to have been patched together
via a pretty hairy process. But there is an XSLT stylesheet that can
take XML input (not DocBook, but similar) and create the HTML output
you see. I contacted the guy that wrote the stylesheet for his
thoughts.
I came across this example of DocBook:
RELAX NG Compact Syntax Tutorial
Yes, but does he have an XSLT to convert it to meaningful HTML?
Another option is using markdown for authoring and convert it to XHTML
and RNC. Only minor problem with that is pandoc doesn’t have RNC
syntax-highlghting, and I can’t find a kate syntax file for the
language.
Note, a markdown version of the start of the tutorial is in the SVN.
Feel free to add to that.
markdown would seem much friendlier. I did find a reference to a RelaxNG
kate-file, but couldn’t find the link to the file itself:
http://archives.devshed.com/forums/kde-96/new-syntax-file-for-relax-ng-2259437.html
That’s odd; just use the XML highlighter.
It might be worth looking into how hard it is to write a syntax file.
Bruce
Would you be happy with the syntax highlighting of SourceForge? (e.g. “
http://xbiblio.svn.sourceforge.net/viewvc/xbiblio/csl/schema/trunk/csl.rnc?view=markup”)
Sourceforge apparently uses ViewVC for the Subversion browser interface, and
ViewVC again depends on Pygments (http://pygments.org/) for syntax
highlighting. I don’t know which syntax file Pygments uses for the schema
though (I couldn’t find a hint in the HTML source). If you have Pygments
installed you can find out which parser it uses:
http://pygments.org/docs/quickstart/#guessing-lexers
Rintze
It might be worth looking into how hard it is to write a syntax file.
Would you be happy with the syntax highlighting of SourceForge?
Yes, definitely.
(e.g. “XBib download | SourceForge.net”)
Sourceforge apparently uses ViewVC for the Subversion browser interface, and
ViewVC again depends on Pygments (http://pygments.org/) for syntax
highlighting. I don’t know which syntax file Pygments uses for the schema
though (I couldn’t find a hint in the HTML source). If you have Pygments
installed you can find out which parser it uses:
Introduction and Quickstart — Pygments
It doesn’t understand RNC out-of-box. So your question is a good one.
Bruce
Sourceforge has been acting up a bit for the last few days. I checked the
HTML again, and the only hints of which lexer is used seem to be some tags
in the parsed output (e.g. text), e.g. compare:
http://xbiblio.svn.sourceforge.net/viewvc/xbiblio/csl/schema/branches/split/csl-core.rnc?revision=995&view=markup
with
http://xbiblio.svn.sourceforge.net/viewvc/xbiblio/csl/schema/tags/0.8/csl.rng?revision=951&view=markup
If you still have Pygments installed, could you do a grep on the unique
strings of these tags: “hl kwa”, “hl slc”, “hl str” and “hl kwb”? Maybe it
will identify the lexer.
Best regards,
Rintze
Whoops, scrap that, they’re just standard identifiers (
http://xbiblio.svn.sourceforge.net/viewvc-static/styles.css). I’ll try to
figure out how to write a Kate syntax file for RELAX NG Compact, then.
RintzeOn Wed, Jun 17, 2009 at 7:22 AM, Rintze Zelle <@Rintze_Zelle>wrote: