summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/photobook/scripts/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/photobook/scripts/README.md')
-rw-r--r--Master/texmf-dist/doc/latex/photobook/scripts/README.md38
1 files changed, 21 insertions, 17 deletions
diff --git a/Master/texmf-dist/doc/latex/photobook/scripts/README.md b/Master/texmf-dist/doc/latex/photobook/scripts/README.md
index 2e00881f705..7befc142281 100644
--- a/Master/texmf-dist/doc/latex/photobook/scripts/README.md
+++ b/Master/texmf-dist/doc/latex/photobook/scripts/README.md
@@ -23,8 +23,6 @@ Support scripts
`make-spreads.sh`
----------------
-<!-- XXX add a TL;DR, "quick start" or "cheat sheet" section... abstract? -->
-
Generate LaTeX block of pages/spreads from a directory tree.
This was initially intended as a means to convert the exported directory
@@ -52,7 +50,7 @@ book/
│ ├── image-image.tex
│ ├── fullbleed.tex
│ └── ...
-├── spreads/ . . . . . . . . . . . . . . Main block layout.
+├── spreads/ . . . . . . . . . . . . . Main block layout.
│   ├── 00/ . . . . . . . . . . . . . . A basic spread.
│   │   ├── tweaks.tex The spread template is built
│   │   └── 0-DSC02432.jpg automatically with tweaks.tex
@@ -79,23 +77,22 @@ book/
├── block.tex . . . . . . . . . . . . . Block skeletal layout.
│ This usually includes the titles,
│ technical pages and sources the
-│ ./block-pages.tex.
-├── block-pages.tex . . . . . . . . . . The generated block content.
+│ ./block-spreads.tex.
+├── block-spreads.tex . . . . . . . . . The generated block content.
├── cover.tex . . . . . . . . . . . . . Cover layout.
├── jacket.tex . . . . . . . . . . . . Dust jacket layout.
└── ...
```
-<!-- XXX
-For a live example see: ../examples/book -->
+For a full example see: ../examples/book
Generate the block:
```shell
-$ make-spreads.sh ./pages > block-pages.tex
+$ make-spreads.sh ./spreads > block-spreads.tex
```
Note that `make-spreads.sh` does not force a specific layout outside of
-the `pages` directory, all paths are configurable. The way the root
+the `spreads` directory, all paths are configurable. The way the root
files are structured in this example is just one way to organize a
book's source code with minimal code duplication.
@@ -123,20 +120,20 @@ work is starting to look like a book.
When starting work on a layout it is good to at least have a basic
understanding of the book's:
- structure and how it may change,
-- core templates,
+- general look (i.e. core templates),
- exceptions from the above.
In most cases all of the above will change in one way or another during
the project's lifespan, and the main goal of this stage is to make this
-change as simple as possible -- it's all about providing the freedom to
-make changes instead of growing work invested and thus making change
-more and more expensive.
+change as efgortless as possible -- it's all about providing the freedom
+to make changes instead of growing the work invested and thus making
+change more and more expensive.
The first question is what is the _structure_ of the book we are making?
Will it have chapters? How many? Text? how much, how should it be
-structured? How are we going to deal with the title? How are we going
+placed? How are we going to deal with the title? How are we going
to present the images, full bleed, no bleeds, small, big, one per page
-or multiple images, ...etc.? At this stage this is about the presentation
+or multiples, ...etc.? At this stage this is about the presentation,
the flow of the work and not about the actual design. How many typical
spreads (i.e. spread templates) should it have? A good number should be
small-ish, for example 3-4 spread templates is a good number, if you
@@ -313,7 +310,7 @@ environment variable.
Inline captions are also supported:
```bnf
-pages/
+spreads/
├── <spread>/
│   ├── ...
│   ├── 00-<image-name>.<ext>
@@ -389,6 +386,13 @@ $ make-spreads.sh -c <path> ..
Extract the documentation from photobook.cls which is used to build the
photobook.pdf reference manual.
+This makes it possible to keep the documentation and code it describes
+in the same place/file.
+
+The format is in part inspired by LaTeX's [.dtx](http://tug.ctan.org/info/dtxtut/dtxtut.pdf)
+format but is far simpler and retains human readability with less effort.
+
+
```shell
$ cls2tex.sh --help
```
@@ -440,4 +444,4 @@ NOTE: the idea of keeping latex docs in a latex file is far simpler
in both the repo and in installed form, so .dtx is not used.
```
-
+<!-- vim:set ts=4 sw=4 nowrap : -->