Skip to content

Latest commit

 

History

History
126 lines (82 loc) · 3.37 KB

SPEC.asciidoc

File metadata and controls

126 lines (82 loc) · 3.37 KB
Raw

The Dream

This is where I’m documenting basically what I want the README to eventually look like. This is sort of my Document Driven Development file. I’m trying to envision what the git-scribe project should look like as I write the tool. I didn’t want it to be in the readme yet so as not to confuse people. All the commands are just ideas and what not. If you have an idea of how you would like things to look, add them here and send a pull request.

I want to get the full workflows worked out here (with technical details) before I even try to implement them.

Start a Book

$ git scribe init (--type=[code,math]) (--license=[public,cc]) (--lang=en) [project]

Generates a skeleton, license file and readmes with instructions for authors and contributors. Also records version of scribe workflow we’re using into .gitscribe file.

  • shows cheat-sheet of how to use grep, tag, diff (--word)

Work on a Book

$ git scribe check

Run checks to make sure you have all the tools you need and your system can do stuff.

$ git scribe register (--role=[author,reviewer,editor,translator])

Register yourself and your role in this book. kept in .git/scribe

To Do List

$ git scribe todo

  • lists boilerplate you still haven’t filled out (title, author, description, chapter, cover, bio, biblio, price, license, etc) most of that is kept in .gitscribe

Writing

$ git scribe new chapter

Editing

$ git scribe review

TODO: address technical reviewing and copy-editing

Translating - Translator

$ git scribe trans start (--edition=1.1) de

Sets up pre-commit hook to check that commit message is formatted correctly, copies over main language to de

$ git scribe trans changes (--since=2010-01-01)
$ git scribe trans done SHA

Translating - Maintainer

$ git scribe trans complete

See which translations are what percent complete.

  • get list of translators for each translation

Editions

This is meant to be done infrequently - like an edition of a book or a major version of a framework that is being documented. Publishing editions too often makes work difficult on translators, so be prudent.

$ git scribe --tool-version=1.7 publish [major|minor]

Tags the edition with the next major or minor number, generates a branch for maintainance for this edition.

Generate Media

$ git scribe gen (--lang=de) (--edition=1.0) [site,pdf,mobi,epub]

OR

$ git push origin

Sell

$ git scribe sell --price=8.00 [--lang=de] (ibooks,kindle,nook,lulu)

Layout

The layout that the git scribe init produces looks like this:

* book/
|`--* book.asc
|`--* 01_first_chapter.asc
|`--* 02_second_chapter.asc
|`--* 99_backmatter.asc
|`--* image/
|    `--* 01.01-example-image.png
|    `--* 01.02-another-image.png
|    `--* 02.01-an-image.png
|`--* include/
|    `--* 02.01-code.c
* style/
|`--* style.css
* site/
|`--* layout.html
* test/
|`--* 01_test.rb
* LICENSE.txt
* README.asciidoc
* .gitscribe

Not all of those files would be generated (like the test files and the site files which are overrides for the site templates), but examples would and it would give a usable starting point for new authorship. This example would be a valid and somewhat complex layout.