blob: 69928632346e5325a172eb46cad1b20d471edfb8 (
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
|
\skbheading{Separate Content from Structure: the Repository Folder}
Now, separating the structure from the content first. The structure of a
document (we stay with classic text documents like articles, books, etc.
for a while) is words in sentences in paragraphs in (sub-) sections in
chapters (if its a book, of not only sections)\footnote{One very
meticulous person might add 'characters' and mention that there are more
ways to think about a document's structure. But that person is not me. The
structure I used fits the purpose (as of now), if it doesn't anymore I
will look further.}. We collect sentences and paragraphs but separate them
from headings. \LaTeX is doing that already with the macros for chapters and
sections. We go one step further and provide a generic way to identify a
heading with the \SKB~macro \cmd{\setheading}. This allows to select the appropriate
\LaTeX heading level at a later stage having the context of that later stage in mind
(i.e. it might be a section in an article but a chapter in a book). Now we create
a structure for the resulting files in our repository, adding meaningful names to
the directories and files. Obviously the names of these folders should provide some
idea about the general characterisation of the files they contain. Example? Well, if you collect
information from Standard Defining Organisations (SDOs) the top folder
could be named \skbem[code]{sdo} and the sub-folders using the
respective SDO acronyms, such as \skbem[code]{omg} for the OMG and
\skbem[code]{ieee} for the IEEE and \skbem[code]{ietf} for the IETF. We put all this in
a folder named repository, making it explicit that here is were we find all our normative content.
\opt{text}{The following example}\opt{note}{This slide} shows how that looks like.
\opt{text}{
\begin{longtable}{|>{}p{0.945\textwidth} >{}p{1pt}|}
\hline
\rowcolor[gray]{.9}
\skbinput[from=fig]{dirtree/repository}
& \\
\hline
\end{longtable}
\addtocounter{table}{-1}
}
The result: we have a structure of files, containing our 'stuff',
integrated in a structure of folders that allows us to find it (the better
this structure the more helpful it is, and remember this is a 'personal'
repository, so your personal flavour is king).
|