summaryrefslogtreecommitdiffstats
path: root/data/doc/sisu/markup-samples/v4/sisu_manual/sisu_content_directories.ssi
blob: 182b176da8d7ada00be285a53389b5edea8bcac5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
% SiSU insert 2.0

@title: SiSU
 :subtitle: Content Directories, Organising Content

@creator:
 :author: Amissah, Ralph

@date:
 :created: 2002-08-28
 :issued: 2002-08-28
 :available: 2007-08-28
 :published: 2007-09-16
 :modified: 2011-02-07

@rights:
 :copyright: Copyright (C) Ralph Amissah 2007
 :license: GPL 3 (part of SiSU documentation)

:A~? Organisation of Content

:B~? Content Directories

1~organising_content Organising Content - Directory Structure and Mapping

SiSU v3 has new options for the source directory tree, and output directory structures of which there are 3 alternatives.

2~ Document Source Directory

The document source directory is the directory in which sisu processing commands are given. It contains the sisu source files (.sst .ssm .ssi), or (for sisu v3 may contain) subdirectories with language codes which contain the sisu source files, so all English files would go in subdirectory en/, French in fr/, Spanish in es/ and so on. ISO 639-1 codes are used (as varied by po4a). A list of available languages (and possible sub-directory names) can be obtained with the command "sisu --help lang" The list of languages is limited to langagues supported by XeTeX polyglosia.

3~ General Directories

code{

./subject_name/

% files stored at this level e.g. sisu_manual.sst or
% for sisu v3 may be under language sub-directories
% e.g.

./subject_name/en

./subject_name/fr

./subject_name/es

./subject_name/_sisu

./subject_name/_sisu/css

./subject_name/_sisu/image

}code

2~ Document Output Directory Structures

3~ Output Directory Root

The output directory root can be set in the sisurc.yml file. Under the root, subdirectories are made for each directory in which a document set resides. If you have a directory named poems or conventions, that directory will be created under the output directory root and the output for all documents contained in the directory of a particular name will be generated to subdirectories beneath that directory (poem or conventions). A document will be placed in a subdirectory of the same name as the document with the filetype identifier stripped (.sst .ssm)

The last part of a directory path, representing the sub-directory in which a document set resides, is the directory name that will be used for the output directory. This has implications for the organisation of document collections as it could make sense to place documents of a particular subject, or type within a directory identifying them. This grouping as suggested could be by subject (sales_law, english_literature); or just as conveniently by some other classification (X University). The mapping means it is also possible to place in the same output directory documents that are for organisational purposes kept separately, for example documents on a given subject of two different institutions may be kept in two different directories of the same name, under a directory named after each institution, and these would be output to the same output directory. Skins could be associated with each institution on a directory basis and resulting documents will take on the appropriate different appearance.

3~ Alternative Output Structures

There are 3 possibile output structures described as being, by language, by filetype or by filename, the selection is made in sisurc.yml

code{

#% output_dir_structure_by: language; filetype; or filename
output_dir_structure_by: language   #(language & filetype, preferred?)
#output_dir_structure_by: filetype
#output_dir_structure_by: filename  #(default, closest to original v1 & v2)

}code

3~ By Language

The by language directory structure places output files

The by language directory structure separates output files by language code (all files of a given language), and within the language directory by filetype.

Its selection is configured in sisurc.yml

output_dir_structure_by: language

% works for html epub odf, pdf, sortof for info NOT for man pages

code{

    |-- en
    |-- epub
    |-- hashes
    |-- html
    | |-- viral_spiral.david_bollier
    | |-- manifest
    | |-- qrcode
    | |-- odt
    | |-- pdf
    | |-- sitemaps
    | |-- txt
    | |-- xhtml
    | `-- xml
    |-- po4a
    | `-- live-manual
    |     |-- po
    |     |-- fr
    |     `-- pot
    `-- _sisu
        |-- css
        |-- image
        |-- image_sys -> ../../_sisu/image_sys
        `-- xml
            |-- rnc
            |-- rng
            `-- xsd

}code

#by: language
subject_dir/en/manifest/filename.html

3~ By Filetype

The by filetype directory structure separates output files by filetype, all html files in one directory pdfs in another and so on. Filenames are given a language extension.

Its selection is configured in sisurc.yml

output_dir_structure_by: filetype

% works for html epub odf, pdf, sortof for info NOT for man pages

code{

    |-- epub
    |-- hashes
    |-- html
    |-- viral_spiral.david_bollier
    |-- manifest
    |-- qrcode
    |-- odt
    |-- pdf
    |-- po4a
    |-- live-manual
    |     |-- po
    |     |-- fr
    |     `-- pot
    |-- _sisu
    | |-- css
    | |-- image
    | |-- image_sys -> ../../_sisu/image_sys
    | `-- xml
    |     |-- rnc
    |     |-- rng
    |     `-- xsd
    |-- sitemaps
    |-- txt
    |-- xhtml
    `-- xml

}code

#by: filetype
subject_dir/html/filename/manifest.en.html

3~ By Filename

The by filename directory structure places most output of a particular file (the different filetypes) in a common directory.

Its selection is configured in sisurc.yml

output_dir_structure_by: filename

% works for html epub odf, pdf, sortof for info NOT for man pages

code{

    |-- epub
    |-- po4a
    |-- live-manual
    |     |-- po
    |     |-- fr
    |     `-- pot
    |-- _sisu
    | |-- css
    | |-- image
    | |-- image_sys -> ../../_sisu/image_sys
    | `-- xml
    |     |-- rnc
    |     |-- rng
    |     `-- xsd
    |-- sitemaps
    |-- src
    |-- pod
    `-- viral_spiral.david_bollier

}code

#by: filename
subject_dir/filename/manifest.en.html

3~ Remote Directories

code{

./subject_name/

% containing sub_directories named after the generated files from which they are made

./subject_name/src

% contains shared source files text and binary e.g. sisu_manual.sst and sisu_manual.sst.zip

./subject_name/_sisu

% configuration file e.g. sisurc.yml

./subject_name/_sisu/skin

% skins in various skin directories doc, dir, site, yml

./subject_name/_sisu/css

./subject_name/_sisu/image

% images for documents contained in this directory

./subject_name/_sisu/mm

}code

3~ Sisupod

code{

./sisupod/

% files stored at this level e.g. sisu_manual.sst

./sisupod/_sisu

% configuration file e.g. sisurc.yml

./sisupod/_sisu/skin

% skins in various skin directories doc, dir, site, yml

./sisupod/_sisu/css

./sisupod/_sisu/image

% images for documents contained in this directory

./sisupod/_sisu/mm

}code

2~ Organising Content



% .SH "SKINS \- document, directory and site skins"