~mieum/booksin.space

61df76f6e4e62077844eaab0131be9690f4c4cdb — mieum 4 months ago f497385 master
Update submission formatting guidelines

Updates the desired format for title, author, etc. in the
submission template, and tidies it up a little bit. Also
makes corrects and improvements to README to reflect these
changes.
2 files changed, 38 insertions(+), 32 deletions(-)

M README.md
M cataloging/template.yml
M README.md => README.md +23 -18
@@ 10,7 10,7 @@ If you'd like to get involved, visit the [mailing list](https://lists.sr.ht/~mie

The books in our library are all in text/gemini (gemtext) format. To contribute a book to our shelves, simply produce a gemtext version, complete and prepend the necessary YAML frontmatter (using [this template](cataloging/template.yml)), then submit the .gmi/.gemini file as a patch to the [mailing list](https://lists.sr.ht/~mieum/booksin.space). If you are unfamiliar with git and sending patches but would still like to contribute a book, attaching a .gmi/.gemini file to your email works too :)

All texts contributed as patches should be deposited in the `cataloging` folder. The filename should contain no spaces, and be descriptive of the content (e.g., `gibran_the-prophet.gmi`). The `cataloging` folder also contains a [template](cataloging/template.yml) to be completed and prepended to each individual text submitted. The only metadata required for submission are: author, title, language, and license. The optional data is used for building indexes to facilitate browsing the library by different categoires, such as by publication, publisher, etc., and it is also used to generate bibtex files for each individual item in the library.
All texts contributed as patches should be deposited in the `cataloging` folder. The filename should contain no spaces, and be descriptive of the content (e.g., `gibran_the-prophet.gmi`). If submitting a gempub archive along with the gemtext version, please be sure that their filenames are uniform. The `cataloging` folder also contains a [template](cataloging/template.yml) to be completed and prepended to each individual text submitted. The only metadata required for submission are: author, title, language, and license. The optional data is used for building indexes to facilitate browsing the library by different categoires, such as by publication, publisher, etc., and it is also used to generate supplementary content, such as gempub archives or bibtex files for each individual item in the library.

```
---


@@ 18,26 18,27 @@ All texts contributed as patches should be deposited in the `cataloging` folder.
# booksin.space library. MIND THE WHITESPACE :)

# required fields
title: 
author: # use list syntax for multiple authors:
- Unknown # unkown is OK
- Anonymous # anonymous is OK
lang: # language code (e.g., 'en' for English, 'ko' for Korean, etc.)
license: # eg. public domain, CC-BY, etc.

# optional fields, delete what you don't need :)
attribution: # additional information required by license
title: Prophet, The     # Split title if it begins with 
                        # an article ('the', 'an,' 'a,' etc.)
author:                 # use list syntax for multiple authors:
- Gibran, Khalil        # Surname, Given Name 
- Unknown               # unkown is OK
- Anonymous             # anonymous is OK
- 壯子                  # single name is OK
lang:                   # language code (e.g., 'en' for English, 
                        # 'ko' for Korean, etc.)
license:                # eg. public domain, CC-BY, etc.

# optional fields, feel free to delete what you don't need :)
attribution:    # additional information required by license
date:
genre:
editor: # use list syntax for multiple editors
- editor one
- editor two
translator: # use list syntax for multiple translators
- translator one
- translator two
editor:         # same formatting as 'author' values above
translator:     # same formatting as 'author' values above
publisher:
city:
publication:
  title: # same formatting as 'title' values above
  volume: # arabic numerals
  issue: # arabic numerals
  pages:


@@ 48,7 49,7 @@ publication:
---
```

**NOTE:** The YAML frontmatter begins and ends with a triple dash ("---"). Copy and paste everything, including the triple dashes, into the beginning of your submission. Remove any optional fields you do not need, and add any that you do.
**NOTE:** The YAML frontmatter begins and ends with a triple dash ("---"). Copy and paste everything, including the triple dashes, into the beginning of your submission. Remove any optional fields you do not need, and add any that you do. The YAML frontmatter will be removed from the text and appended to a master metadata file for the item once cataloged.

### Submission Guidelines 



@@ 68,7 69,11 @@ Our library will accept any texts with a free license, such as books in the publ

We are a library, but being that all (or most) of our books are new recreations of existing texts, we are also a kind of pseudo-publisher. There are no formal style rules to which submissions must adhere, however. If you want to make a sweet ASCII banner (cover) for the book you are submitting, that's awesome! If you want to use superscripts for footnotes or pandoc-style footnote syntax, it's all gravy. In general, the rule of thumb is **consistency**. It is unreasonable to expect all texts of all types in all languages from all time periods to adhere to the same style rules. Take whatever license you need to make your submission look good and make sense. Just be sure that whatever formatting and styling decisions you make are consistent throughout the text.

With that said, please submit texts as a single file. Do not separate a book into multiple chapters/files. It may be desirable for longer texts to be available in per-chpater formats, but this feature is best handled by the shelving utility and may be added at a later date.
With that said, there are a couple guidelines for making things easier for everyone:

1. Please submit texts as a single file. Do not separate a book into multiple chapters/files. It may be desirable for longer texts to be available in per-chapter formats, but dividing texts into chapters would be better handled by the shelver/symlinker utility itself. **Gempub archives are an exception if submitted in addition to an ordinary gemtext version.**

3. Each gemtext book should be a standalone text; meaning, **please include the title as a first-level heading and the author's name in a byline below it.** People should know what they are looking at when they open the file (even the cataloguer script!) :b

#### Acceptible Content


M cataloging/template.yml => cataloging/template.yml +15 -14
@@ 3,26 3,27 @@
# booksin.space library. MIND THE WHITESPACE :)

# required fields
title: 
author: # use list syntax for multiple authors:
- Unknown # unkown is OK
- Anonymous # anonymous is OK
lang: # language code (e.g., 'en' for English, 'ko' for Korean, etc.)
license: # eg. public domain, CC-BY, etc.
title: Prophet, The     # Split title if it begins with 
                        # an article ('the', 'an,' 'a,' etc.)
author:                 # use list syntax for multiple authors:
- Gibran, Khalil        # Surname, Given Name 
- Unknown               # unkown is OK
- Anonymous             # anonymous is OK
- 壯子                  # single name is OK
lang:                   # language code (e.g., 'en' for English, 
                        # 'ko' for Korean, etc.)
license:                # eg. public domain, CC-BY, etc.

# optional fields, delete what you don't need :)
attribution: # additional information required by license
# optional fields, feel free to delete what you don't need :)
attribution:    # additional information required by license
date:
genre:
editor: # use list syntax for multiple editors
- editor one
- editor two
translator: # use list syntax for multiple translators
- translator one
- translator two
editor:         # same formatting as 'author' values above
translator:     # same formatting as 'author' values above
publisher:
city:
publication:
  title: # same formatting as 'title' values above
  volume: # arabic numerals
  issue: # arabic numerals
  pages: