See previous discussions and proposals:
In the current proposal we are to indicate the publication status of a document in a JSON file included in the directory. I wonder whether we should, rather, do this using git branches.
Have a JSON file with publication data, including publication status. This would be included at the top folder level in bilara-data. This has the advantage that all publication data is included in one place, and can act as a master reference for all SC’s publications. However I fear it may have some problems:
- How do we handle complex cases where a translator wishes to publish certain texts in a nikaya and not others? They might have to make a list of hundreds of sutta UIDs in JSON. This would be brittle and error-prone.
- The publication status of a particular text is not evident in the Github UI. Someone looking at the repo wouldn’t know what is published and what isn’t, unless they read the JSON file.
Distinguishing between “published” and “unpublished” branches is of course one of the basic functions of Git. Rather than reinventing the wheel, why not use this for texts, just as we do for code?
- Under this model, when a translator begins work on Bilara, their work is opened on an
unpublishedbranch in Bilara. Anyone looking at the Bilara repo immediately knows what is what.
- When ready to publish, that branch is merged with the
publishedbranch. In this scenario, it is, I think, better to call this branch
master, which is not really meaningful.
- Anything on the
publishedbranch is “ready to consume” by any app that wants it. Typically we’d expect that apps would mirror the published content and serve it from their own repo.
- Note that in some cases, apps will want to transform the data in different ways. For example, on SC we want to turn markdown emphasis into HTML
<em>tags, whereas for a voice app they may be removed.
How would this be handled in terms of UI? I’m thinking that work in Bilara is always committed to
unpublished. There is a button in the bilara toolbar, PUBLISH. When you hit that, it opens a modal dialog or something like that. The data for
publication.json is entered via this modal, or automatically generated. Thus normally
publication.json would not be hand-edited (which is a change from my original proposal.)
In the following mockup, I use italics for text that will be autopopulated.
This action will publish your translation publicly to SuttaCentral.net, as well as any services that use SuttaCentral’s texts
Before publishing, ensure that texts are proofread and all corrections are made.
Root title: Majjhima Nikāya
Translated title: Middle Discourses
Author UID: sujato
Full name: Bhikkhu Sujato
Short name: Sujato
☐ Publish all changes to collection Middle Discourses.
Publish only this text (MN 1) to collection Middle Discourses.
☐ Unpublish all texts from collection Middle Discourses.
☐ Unpublish only this text (MN 1) from collection Middle Discourses.
☐ Draft: this work is incomplete and will be revised.
Completed: the main work on this text is complete, but corrections and improvements are ongoing.
☐ Final: no further revision is anticipated.
☐ Initial publication.
☐ Minor update. Use this for simple corrections and minor revisions. This update will not be recorded in the publication data, but is retained in Github.
Revised edition. Use this for a substantially revised new edition. This update will be recorded in the publication data.
- text field for revised editions: “Describe the nature of the revision (required)”.
All publications made on Bilara must use a Creative Commons Zero license. The author or authors dedicate the work to the Public Domain. This dedication is irrevocable.
Check these details are correct
Publish a completed version of a revised edition of MN 1 in Middle Discourses by Bhikkhu Sujato.
Then the relevant data would be automatically added to
Let’s break this down.
The root text title and ID are set up in a separate process at the start of the project. The root text is basically what would normally be considered a “book”, i.e. a nikaya, a book of the Khuddaka, one of the Vibhangas or Khandhakas, a book of the Abhidhamma, etc.
Like the title info, the translator data is already set up at the start of the project.
The Publication Action is by default set to the whole collection.
However a translator may want to work progressively. Imagine for example that someone wishes to translate a Samyutta sutta every day. Then they set the publication action to “this text only”. Then:
- If the collection is not yet published, it is created in
publication.jsonand the specific text ID added.
- If the collection is already published, the ID is added.
- If the text is already published, but is revised, it is simply pushed.
A translator should also have the ability to unpublish work.
This is a note to let readers know the current status of the project. It might be used, for example, to trigger a “draft” flag on the website.
We want to be able to note substantial changes, however we need not record every corrected comma in
publication.json: that’s what git is for. The only way to do this is to rely on the translator.
Initially, “initial publication” is automatically checked and other options are disabled. Once the commit is made, the situation reverses: Initial publication is disabled, and “minor update” is checked. The translator can choose to check “revised edition”.
- “Initial Publication”: This creates the relevant entry in
- “minor update”. Changes will be logged in git with generic commit message, but not recorded in
- “Revised edition”, the date and commit number will be added as a new edition to
publication.json. In addition, they will have to add some text describing the revised edition. This will be the commit message, and also will be added to
Check the details
We’ll want to make sure everything is right.
Details added by system
Certain details can be left out of this dialog for simplicity, and will be added automatically to
publication.json. These will include;
- Publication number:
- Source URL
- CC0 license
- edition number (if needed)
- publication date/time
- If individual suttas are added to a collection over a period of time, the date/time records only the first and last times as a range.
- Publisher name “SuttaCentral”
- Publication type and URL. In some cases these may have to be added by hand later, eg. for books.