A few questions on docs

@Rintze_Zelle - just a couple of followups on the docs discussion on github. Posting here in case anyone else has input.

  1. As I was thinking to split the csl.rnc file into a few more files, I was thinking to model it based on the structure of the spec doc. Are you happy with that?
  2. I noticed the XML fragments don’t have syntax highlighting. Searching around a bit turns up this was a limitation of the theme, but that it has been fixed and merged to RTD. Is there something you need to do to update the theme?
  3. You might update the copyright date.

Actually, on 2, more complicated than I thought. The 1.0.1 version of the spec that opens by default doesn’t have syntax-highlighting, but the master version does. Not sure why.

On 1, I was wondering about moving sections 2-4 to the “style” section, and demoting them in the hierarchy?

At least that’s what I would do if splitting csl.rnc further.

IIRC, I based the structure of the CSL specification on the structure of the CSL schema, so sure. I would just try to make sure that the various files have a clear scope and clear dependencies so people don’t lose track of what’s described where.

I think we just need to rebuild the documentation for each version. It’s been a while since I looked, but we can probably trigger rebuilds from the Read the Docs admin console. “master” has had recent commits, so that version has already been built since the syntax highlighting was fixed in RTD.

1 Like