summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/skb/doc/user-guide/repository/separate
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/skb/doc/user-guide/repository/separate')
-rw-r--r--macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-cs.tex41
-rw-r--r--macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-final.tex11
-rw-r--r--macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-baf.tex55
-rw-r--r--macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-pc.tex43
-rw-r--r--macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-pc2.tex37
-rw-r--r--macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts.tex6
-rw-r--r--macros/latex/contrib/skb/doc/user-guide/repository/separate/separate.tex21
7 files changed, 214 insertions, 0 deletions
diff --git a/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-cs.tex b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-cs.tex
new file mode 100644
index 0000000000..6d0a6c8863
--- /dev/null
+++ b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-cs.tex
@@ -0,0 +1,41 @@
+\opt{text}{\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 \skbacft{A3DS: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 \acs{SDO} the top folder
+could be named \skbem[code]{sdo} and the sub-folders using the
+respective \ac{SDO} acronyms, such as \skbem[code]{omg} for the \skbacft{organisation:OMG} and
+\skbem[code]{ieee} for the \skbacft{organisation:IEEE} and \skbem[code]{ietf} for the
+\skbacft{organisation: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). \ No newline at end of file
diff --git a/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-final.tex b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-final.tex
new file mode 100644
index 0000000000..ffe623d832
--- /dev/null
+++ b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-final.tex
@@ -0,0 +1,11 @@
+\opt{text}{\skbheading{The Final Directory Structure}}
+
+As this is the final and complete root directory of our repository:
+\begin{longtable}{|>{}p{0.945\textwidth} >{}p{1pt}|}
+ \hline
+ \rowcolor[gray]{.9}
+ \skbinput[from=fig]{dirtree/complete}
+ & \\
+ \hline
+\end{longtable}
+\addtocounter{table}{-1} \ No newline at end of file
diff --git a/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-baf.tex b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-baf.tex
new file mode 100644
index 0000000000..e023fa7110
--- /dev/null
+++ b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-baf.tex
@@ -0,0 +1,55 @@
+\opt{text}{\skbheading{Bibliography, Acronyms and Figures}}
+
+So the combination of \LaTeX~and \BibTeX~already helps us for this separation.
+Using the acronym package, we can extend this to acronyms. Looking into the highly
+common re-use of figures, we should look into this as well. Let's take the organisation
+of bibliographic information as a template. I store them using \BibTeX and process them
+with the biblatex package (but that is not critical for now). My \BibTeX database is in
+a special folder (we can call it \skbem[code]{references} for the moment) and it uses
+a file structure that helps me to find information. This structure is based on the \BibTeX
+and biblatex classification, i.e. inproceedings, article, book, thesis, standard, etc.
+
+Now, I can do the same for figures: put them into a special folder (we can call it
+\skbem[code]{figures} for the moment), which contains the source of the figures and the
+generated formats I need for my documents (usually \skbacft{ISO:PDF}, some \skbacft{ISO:PNG}). Now I can reference these
+figures from the repository as well as for other use cases, such as web publishing or
+presentations\footnote{My figures are exclusively in \skbacft{W3C:SVG} using inkscape (www.inkscape.org).
+This has the advantage of a standardised, text-based format with many export options. All my
+figures are in a single root folder, structured very similar to the
+document folders created above, but separated from it. This makes re-use of figures very easy.}.
+
+Last not least, the \skbem[code]{acronym} package
+allows for an automatic handling of acronyms, including list of acronyms.
+It is very similar to {\scshape Bib\TeX} in that it will only show the
+acronyms used in a document out of a (potentially large) database.
+
+One might also want to create other specific structures, such as for programming code. Dont'
+stop yourself, it's easier to combine things later (if the separation is not effective) than
+to separate things that are hugely integrated into each other. For one of my internal projects,
+a parser generation environment based on \skbacft{ANTLR}, I created a special folder for the EBNF specifications
+along with railroad diagrams. Now I can use them in my book and my papers.
+
+Now we name the folders for the separated content. This is straight forward, although you might want
+to use different names (don't worry, the skb supports that). We add to the already created repository
+folder the things we need for figures (\skbem[code]{figures}) and combine acronyms and \BibTeX in a
+folder called \skbem[code]{database}, separating the data from all other content~\footnote{Now, the
+reason for the database folder and it's structure
+is that the whole \skbacft{A3DS:SKB} contains more databases, all of which reside here. If you want to simply apply this
+to \LaTeX~documents you might want to use a different strutural approach.}.%
+\opt{note}{This slide shows the resulting directory structure}%
+\opt{text}{
+ Now the directory structure looks like this:
+ \begin{longtable}{|>{}p{0.945\textwidth} >{}p{1pt}|}
+ \hline
+ \rowcolor[gray]{.9}
+ \skbinput[from=fig]{dirtree/baf}
+ & \\
+ \hline
+ \end{longtable}
+ \addtocounter{table}{-1}
+}
+
+What did we do so far? We did separate the different parts of our
+documents. The more clinical you are, the better the result will be. But
+please note: separate as much as you should, not as you could. If you
+don't find a reason for separating 'stuff', then don't do it! \ No newline at end of file
diff --git a/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-pc.tex b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-pc.tex
new file mode 100644
index 0000000000..8c8850d627
--- /dev/null
+++ b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-pc.tex
@@ -0,0 +1,43 @@
+\opt{text}{\skbheading{Publications and Content}}
+
+Here is were it might get slightly more complicated than in the first few
+steps. And you might see already that the reason for that is separation!
+We didn't finish the separation, we have to go one step further. And that
+means to separate now the contents (with the references and acronyms and
+figures) from the reason to publish a document. This last step of
+separation is more conceptual, being focused on the \textit{why?} and
+\textit{where?} and \textit{how?} we publish, rather than being focused on
+the \textit{what?} we publish.
+
+So we do publish for many reasons: articles for research, project
+proposals, reports, lecture notes, standard documents, annotated
+presentations, sometimes even books. We publish for a specific purpose, in
+a specific (soon historic) context, using the requested format (and style
+sheets) and a particular structure of our document that fits the purpose.
+That means we organise and structure our content every time according to
+these constrains. Thus we need a new directory structure for that, since
+we will not reuse that as often as our 'stuff' itself. Remember, we use
+the skb macro \cmd{\skbheading} for headings, not the classical \LaTeX~macros
+like \cmd{\section}, so our files effectively do not contain much information
+about their place in the structure, only that they claim one
+\footnote{Currently experimental, but soon to be ready, there will be an extension
+to the \cmd{\skbheading} macro that allows a little bit more information to be put
+in the repository files. For the moment this is captured in the \cmd{\skbheadingduc} macro.}.
+This comes in handy now, since all we have actually to do is to assign a document heading
+level to every repository file we load. Let's create a folder for the published documents and
+call it \skbem[code]{published} with a set of sub-folders that help us to understand the general
+context of the publication.%
+\opt{note}{My directory structure is shown in this slide}%
+\opt{text}{
+My directory structure could look like this:
+ \begin{longtable}{|>{}p{0.945\textwidth} >{}p{1pt}|}
+ \hline
+ \rowcolor[gray]{.9}
+ \skbinput[from=fig]{dirtree/publish}
+ & \\
+ \hline
+ \end{longtable}
+ \addtocounter{table}{-1}
+}
+
+\opt{text}{\skbinput[from=rep]{separate/separate-parts-pc2}} \ No newline at end of file
diff --git a/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-pc2.tex b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-pc2.tex
new file mode 100644
index 0000000000..95c63a6951
--- /dev/null
+++ b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts-pc2.tex
@@ -0,0 +1,37 @@
+We could, and it usually makes sense to do so, go one step further in that
+separation. This time within the documents in the \skbem[code]{published}
+folder. The reason is the structure of \LaTeX~documents: they do need some
+commands specific to \LaTeX, which we don't necessarily want to mix with the
+commands that input our content (the files from repository).
+So it would make sense to have another pair of documents here, one
+containing all \LaTeX~commands needed to create a document, and one
+containing all the commands that include our content. Say we have a few
+articles for state of the art discussions on \textit{naming},
+\textit{object-models} and \textit{protocols}, we could create
+\opt{text}{the following structure}\opt{note}{the structure shown in this slide}
+for the \skbem[code]{article} folder%
+\opt{text}{:%
+ \begin{longtable}{|>{}p{0.945\textwidth} >{}p{1pt}|}
+ \hline
+ \rowcolor[gray]{.9}
+ \skbinput[from=fig]{dirtree/publish-art}
+ & \\
+ \hline
+ \end{longtable}
+ \addtocounter{table}{-1}
+}
+
+Now everything is structured, thus simple again. If we are looking for content, we go to the
+\skbem[code]{repository} directory and the directory names help us to find what
+we are looking for. If we need a figure, we do the same at the \skbem[code]{figures} directory.
+\skbem[code]{acronyms} and \skbem[code]{bibtex} help with the respective
+other content. If we want a specific published document, we simply check the
+\skbem[code]{published} directory and will have a look into a
+\skbem[code]{tex} sub-directory to see what content is include how.
+
+Good news, the separation is finished! What have we done? We have
+separated the contents from the structure by creating, created a separate directory structure for
+figures, another one for bibliographic data, one for acronyms and finally a
+complete directory structure for published documents. Content and title
+form a pair, include figure, use acronyms and references and are combined
+in the published documents. At this point we can start calling it document repository. \ No newline at end of file
diff --git a/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts.tex b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts.tex
new file mode 100644
index 0000000000..2d76689aac
--- /dev/null
+++ b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate-parts.tex
@@ -0,0 +1,6 @@
+\opt{text}{\skbheading{Separating different Parts of a Document}}
+
+The next step is to separate the remaining parts of a document based
+on their semantics. You are probably doing that already if you
+maintain a database for bibliographic information and have many of
+your articles using it. But we can and should do much more than that. \ No newline at end of file
diff --git a/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate.tex b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate.tex
new file mode 100644
index 0000000000..0aedaea043
--- /dev/null
+++ b/macros/latex/contrib/skb/doc/user-guide/repository/separate/separate.tex
@@ -0,0 +1,21 @@
+\opt{text}{\skbheading{The Concept: Separate Things}}
+
+You already got the idea that separation is important, reading about published documents and
+a normative repository. The basic idea is: think separation -- separate as much as you can, but
+not more. I know that this sounds like a strange idea when the goal is a unified repository, but it is
+essential. So we separate several concerns (taking a concept of distributed system design). So if we
+want to facilitate re-usability, we have to:
+\begin{skbnoteenum}
+ \item separate content of a document from its structure and
+ \item separate the different parts of a document.
+\end{skbnoteenum}
+
+\noindent For the impatient:
+\begin{skbnoteenum}
+ \item Separating content from structure means to identify small, coherent blocks of information, i.e.
+ text describing a certain aspect or an example, and put them separated into the repository folder.
+ \item Separating parts of a document means to separate the part that is important for publishing from
+ the part that is important for the content and put them into different places (one in the publish
+ folder and the other one in the repository older). It also means to build a separate repository
+ for figures, since they could be used in many different small blocks of information.
+\end{skbnoteenum} \ No newline at end of file