For Debian Live Manual to use sisu3: (a) a decision needs to be made as to how
(and where) output files should be presented; (b) a change needs to be made in
where processing instructions are given, and; (c) where the configuration
directory (_sisu) is located; (d) to this end a suggestion is made as to what
initial changes need to be made to the Makefile, (including addressing the
issue of generating missing css files). [repost under new heading, with minor
addition (related to document manifest), I would prefer replies to be posted to
this thread]
to take the easiest first:
(c) in the manual (source) directory, the sisu configuration directory
should be moved out of the language sub-directories and be placed at the
same level as those (language sub-) directories:
manual
|-- bin
|-- de
|-- en
|-- es
|-- fr
|-- it
|-- po
|-- pot
|-- pt_BR
|-- ro
`-- _sisu
instead of (the current):
manual
|-- bin
|-- de
| `-- _sisu
|-- en
| `-- _sisu
|-- es
| `-- _sisu
|-- fr
| `-- _sisu
|-- it
| `-- _sisu
|-- po
|-- pot
|-- pt_BR
| `-- _sisu
`-- ro
`-- _sisu
(a) a decision needs to be made on how output files should be presented,
different output structures are created depending on the choice of
organisation made in the sisu configuration file, whether it is to be by
filetype, filename or language (and filetype), this is set by adding one
of the following lines to the configuration file _sisu/sisurc.yml
#output_dir_structure_by: filetype
#output_dir_structure_by: filename
output_dir_structure_by: language
I tend to favour the by "language" option, (which is the most tested to date)
output examples of each are provided below.
And a choice as to where output files should be placed, consider (this
is not necessary but is used in the examples given):
webserv:
path: '../build'
#path: 'build'
(which is a directory named build created outside and at the same level
as the manual directory) used in this example:
#output_dir_structure_by: filetype
|-- build
|-- manual
|-- epub
|-- live-manual
| `-- [all output files in all languages & file formats other
| than epub placed here]
`-- _sisu
#output_dir_structure_by: filename
|-- build
|-- manual
|-- epub
|-- hashes
|-- html
| `-- live-manual
|-- manifest
|-- odt
|-- pdf
|-- _sisu
|-- sitemaps
|-- txt
|-- xhtml
`-- xml
(different languages are identified by language code attached to
filename)
#output_dir_structure_by: language
|-- build
|-- manual
|-- de
| |-- epub
| |-- hashes
| |-- html
| | `-- live-manual
| |-- manifest
| |-- odt
| |-- pdf
| |-- sitemaps
| |-- txt
| |-- xhtml
| `-- xml
|-- en
| |-- epub
| |-- hashes
| |-- html
| | `-- live-manual
| |-- manifest
| |-- odt
| |-- pdf
| |-- sitemaps
| |-- txt
| |-- xhtml
| `-- xml
|-- es
| `-- ...
|-- fr
| `-- ...
|-- it
| `-- ...
|-- pt_BR
| `-- ...
|-- ro
| `-- ...
`-- _sisu
(language sorted by directory, filenames do not reflect langauge)
(b) processing instructions are given from within the live-manual/manual
directory, rather than individual language sub-directories, they may
take the form:
sisu --html --epub --odt --pdf --verbose en/live-manual.ssm
(for each language directory)
or
sisu --html --epub --odt --pdf --verbose --find live-manual.ssm
(which will find live-manual.ssm in each language directory)
or
sisu --html --epub --odt --pdf --verbose --find live-manual
(which will find live-manual in each language directory)
These instructions should work if the earlier suggestions are followed.
sisu --configure
(invoked once to copy images and css files to their appropriate
locations)
at the end of the run for the manifest to correctly show all language generated
output it must be invoked spcifically to take a poll of the output created.
sisu --manifest --verbose --find live-manual
(c) dealt with first look above
(d) the Makefile
build:
@# FIXME: sisu-concordance sisu-pg sisu-sqlite
cd $(CURDIR)/manual; \
sisu --configure
for LANGUAGE in $(LANGUAGES); \
do \
cd $(CURDIR)/manual; \
sisu-epub -v $${LANGUAGE}/live-manual.ssm; \
sisu-html -v $${LANGUAGE}/live-manual.ssm; \
sisu-odf -v $${LANGUAGE}/live-manual.ssm; \
sisu-pdf -v $${LANGUAGE}/live-manual.ssm; \
sisu-txt -v $${LANGUAGE}/live-manual.ssm; \
done; \
sisu --manifest -v $${LANGUAGE}/live-manual.ssm
or
build:
@# FIXME: sisu-concordance sisu-pg sisu-sqlite
cd $(CURDIR)/manual; \
sisu --configure
for LANGUAGE in $(LANGUAGES); \
do \
cd $(CURDIR)/manual; \
sisu-epub --find -v live-manual.ssm; \
sisu-html --find -v live-manual.ssm; \
sisu-odf --find -v live-manual.ssm; \
sisu-pdf --find -v live-manual.ssm; \
sisu-txt --find -v live-manual.ssm; \
done; \
sisu --manifest --find -v live-manual.ssm
or
build:
@# FIXME: sisu-concordance sisu-pg sisu-sqlite
cd $(CURDIR)/manual; \
sisu --configure
for LANGUAGE in $(LANGUAGES); \
do \
cd $(CURDIR)/manual; \
sisu --epub --html --odf --pdf --txt --find -v live-manual.ssm; \
done; \
sisu --manifest --find -v live-manual.ssm
Other changes to the Makefile result from which output form is selected
and here the files are placed.
(if sisurc.yml changes are made to place them in "../build" clean
becomes)
clean:
rm -rf build
I sent the previous patch to implement these suggestions as a starting
point from which further changes might be made as needed.
Apologies the instructions appear to be long, this is mostly a result of
choices to be made and the examples given. I hope it helps.
Ralph
* Ralph Amissah <ralph.amissah at gmail.com>
[Thu, 10 Nov 2011 12:03:31 -0500], wrote:
> The original patches resent along with Makefile_build_permuations
>
> A bit of hacking on live-manual using sisu3 and ruby 1.9.3
> (unlikely to meet all needs, will return to)
>
> changes to:
>
> * the placement of the configuration directory;
>
> * in sisurc.yml the instruction as to where output should be placed and
> selection of the output directory structure;
>
> * Makefile (sisu processing instructions directory in which given; added
> initialization of output directory takes care of css; make clean)
>
> git format-patch debian/3.0_a8-1 --stdout > sisu_v3.patch
>
> minor modification to run sisu without repeating sisu pre-processing for
> each output file type git format-patch debian/3.0_a8-1 --stdout >
> sisu_v3_alt.patch
>
> Hope it is useful, and thanks Ben Armstrong for all the work and
> feedback. (I will try return to it, soon).
>
--
Ralph Amissah (ralph on irc.oftc.net)
GPG fp: A5F9 C48C 4059 B688 6CC5 7A42 6F78 18A9 B98F 62B1 *
GPG fp: 9267 6F8D E64B CD4B 4880 482E E4AF EBC6 1BB4 B289
Attachment:
signature.asc
Description: Digital signature