The SKB User Guide - SUNET - Swedish University Network's FTP
Contents
1. e Ut enim ad minim veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat e Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur e Excepteur sint occaecat cupidatat non proident sunt in culpa qui officia deserunt mollit anim id est laborum Note both macros will only change the margins of the memoir package is not loaded SFor those who are interested the Lorem Ipsum is the standard phrase commonly used since the 1500s The following examples might have no effect on annotated slides 29 User Manual ejeje Jeje Other usefull Macros Styles and Support for Listings o A few pre defined styles provided o Most of them set a small type writer font o Some provide for line numbers o lstdefinestyle used to reset style to basic parameters Example use within normal text lstinputlisting style generic language TeX example lstinputlisting style generic skbfileroot example toc Example use for beamer frames lstinputlisting style beamer example example lstinputlisting style beamer exampleLN example Listings Styles and Support The SKB comes with a few predefined styles for the listing package Most of them use type writer font in scriptsize arrange a grey box around the listing and set the keywords to Blue4 generic for any generic listing without specifying a language and no li2. italic or type writer text The example above shows the macro skbem with the option bold and italic Emphasising Text Highlighting or emphasising text is an important aspect of many technical documents One can use ETEX macros directly to set text in italic or bold This has the disadvantage that there is no meaningful information given as on why that text is treated in a special way Furthermore when the editor requires to change certain highlights it will be very difficult to go through a large document and figure out which text is to be changed To prevent that from happening one can use Tf Xmacros to actually distignguish between different highlighted text A simple start is provided by the SKB It is simply because at the moment it only supports three different ways and no furhter meaningful information But it is a start The macro skbem comes with three different options The option bold will set the text given in the argument in bold face Similar the option italic will set it italic Last not least the option code will use another SKB macro skbcode for typesetting the argument text This slide shows a few examples along with the resulting type setting skbcode This macro skbcode is a facade for calling the macro 1stinline from the listing package with a basic style that uses type writer font ttfamily 28 User Manual 010 101010 Other usefull Macros Lists Two new environments for lists o skbnotelis
3. a specific file name thus loading myslides slide3 tex both files from the default slides directory In lines 4 amp 5 we change the directory for the notes and request a particular file to be loaded resulting in the slide loaded as myslides theme1 pdf from the slides directory and the annotations loaded as text theme1 tex from the repository Finally in lines 6 amp 7 we change both folders to the repository this loading text theme2 pdf and text theme2 tex from the repository Slides and Citations The macro skbslidecite provides some simple means to add citations to annotated slides It takes two arguments the first one for the type of citation and the second one for the actual citation This second block on this slide shows a simple example The first line states that the slide contains material from a book of Tannenbaum and the second line states that the annotation contains material from an IETF RFC standard documents RFC 1155 Since this macro is very simple any content can be given for the two arguments 25 User Manual 01010101010 Je Headings Files Figures Slides Paths Acronyms and References Commands to access Path and Filenames directly skbfileroot the root directory skbpathroot with 1 argument the root dir 1 skbfileacr the acronym directory and file skbfilebib the reference directory and file skbpathbib the reference directory skbfilerep with 1 argument the repository dir 1
4. have a few articles for state of the art discussions on naming object models and protocols we could create the structure shown in this slide for the article folder Now everything is structured thus simple again If we are looking for content we go to the 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 figures directory acronyms and bibtex help with the respective other content If we want a specific published document we simply check the published directory and will have a look into a 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 12 2 User Manual 2 1 Getting Started User Manual O 000000 Getting Started The SKB Distribution distribution contents start folder MS A The generated PDFs and User Guide Sources Aer an lisos ase eee Sources for the User Guide EA ooo errada aan Ea The generated Documentation EAS o aaron cirri E E ister The User Guide only IES oo The generat
5. is given then the annotation is loaded from a file with the same name as the slide plus the extension tex If this option is used and a name is given then this file will be loaded 24 User Manual ojelejeje Jeje Headings Files Figures Slides Paths Acronyms and References Slides skbslide myslides slidei skbslide myslides slide2 clearpage skbslide annotate myslides slide3 skbslide annotate notefrom rep myslides themei text theme1i skbslide annotate notefrom rep slidefrom rep text theme2 text theme2 NOOB WNE skbslidecite 1 skbslidecite Slide cite tanenbaum andrew book 2003 2 skbslidecite Notes cite standard IETF RFC 1155 This provides the following combinations for skbslide e Slide only argument 1 has the name for the PDF argument 2 is empty e Annotation only argument 1 is empty argument 2 has the name for the TEX option annotate used e Slide with Annotation 1 argument 1 has the name for the PDF argument 2 has the name for the TEX option annotate used e Slide with Annotation 2 argument 1 has the name for the PDF argument is empty option annotate used e do nothing leave both arguments empty In line 1 and 2 we load myslides slide1 pdf and myslides slide2 pdf from the default directory without any annotations and clear the page after that In line 3 we load myslides slide2 pdf and request this slide to be annotated without giving
6. macro 11 The IATEX SKB Package ojejejeje The underlying Concept Separate Parts of the Document Part III Publications Articles e Now look into articles there are a few of them i e Object Naming naming tex Object Models object models tex Protocols protocols tex And a separate folder with the links to repository files tex The Folder publish articles A abba ceca our articles naming e the file creating an article on naming object models tex the file creating an article on object models Protocors Tex ea aAA the file creating an article on protocols CERE e e E a folder containing the tex files that include our content naming tae the file including all content for naming object models tex the file including all content for object models protocolsiter oo gn 00000000000 the file including all content for protocols Publications and Content Part II We could and it usually makes sense to do so go one step further in that separation This time within the documents in the published folder The reason is the structure of ATEX documents they do need some commands specific to ATEX 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 ATEX commands needed to create a document and one containing all the commands that include our content Say we
7. more conceptual being focused on the why and where and how we publish rather than being focused on the 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 skbheading for headings not the classical PTEXmacros like section so our files effectively do not contain much information about their place in the structure only that they claim one 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 published with a set of sub folders that help us to understand the general context of the publication My directory structure is shown in this slide Currently experimental but soon to be ready there will be an extension to the skbheading macro that allows a little bit more information to be put in the repository files For the moment this is captured in the skbheadingduc
8. settings For instance in the files skb cfg and skblocal cfg we should use the respective filename When changing configuration settings elsewhere some other descriptive text should be useful If you want to change the configuration settings for a single document without any directory structure overwriting all default settings from skb sty skb cfg and skblocal cfg and using the current relative path you can use the second examle shown in this slide To trace the configuration settings you can use skboptionsused 17 User Manual 01010101010 Je Getting Started Confguration View Options Used o Macro that can be used to show configuration options e Shows the Change Log and actually used options o Uses package warning to printout information Automatically called at the end of processing main document Example Root path Change Log and Option skb Change log skb root skb sty ug slides noanim tex skb Last set Path File Options skb file root user guide Confguration View Options Used This macro will print out a warning including the currently used configuration information and the change list for each of them For example if the configuration for root has not been changed the output for root will be root skb sty doc but if the configuration for fig has been changed using skbconfig to graphics the output for root will be fib skb sty skbconfig graphics This macro i
9. to produce complete documents For the content in the repository we mark headings with the macro skbheading This macro has no options and no arguments and is simply called with the text for the heading as shown in the first block on this slide Leaving the argument empty will have the same effect as calling the original XIX macros directly with an empty argument The association of a TEX document level with the heading is then defined for the published documents in the publish folder using the macro skbinput This macro provides a number of options and requires one argument The second block on this slide shows a few use cases for skbinput Let s start with the simpliest form one argument only shown in line 1 The macro will look for a file called myfile tex in the root directory of the SKB The file extension tex is automatically added and since we did not specify any special directory the root directory is used instead If the file is not found the macro will throw an error providing the full path and filename it did try to load Line 2 shows how we can load the file myfile tex from the repository folder As you can see the option from is supplied with the argument rep which in fact directs the macro to look for myfile tex in the repository folder Should the file be located in the folder for published documents we simply change the from option to pub as shown in line 3 If from is used and neither pub nor rep is given the macro
10. who just wants to write articles and books The IATEX SKB Package eje 10 The Idea The Intent o Maintain repository for Long living Documents using ATEX o Provide easy access to stuff text figures code examples o Reuse stuff rather than copy n paste it all the time o Allow easy creation of different documents using the same stuff Limit IATEXspecific code simplify the interface between User and ATEX The Intent Provide a TpXpackage that helps to create and maintain a repository for long living documents It s probably not usefull for some short term articles however I learned that most of my short term articles eventually become part of my long term documents Here you go The repository should allow for easy access to stuff text blocks senteces paragraphs sections complete chapters But also to figures code sniplets examples etc And I do want to limit the amount of repetition of information For example if I use a certain example in an article I might want to use the same identical example in a book or a presentation or lecture notes If I only copy the example I have to maintain several sources and over time I will not remember which of them is normative As a side effect I also want to optimise document creation and limit the TfXor document class specific code in my documents The IATEX SKB Package ejeje The Idea Applicability and Side Effects The SKB can be
11. your own computer or laptop e Create a file skblocal cfg in your personal TpXstyle template directory This will be the most convenient way to configure the SKB Note you might need to refresh the file database of your TEX distribution e Use skbconfig in your documents If you chose option 1 we assume you know what you are doing In case you chose options 2 3 you can use the macro skbconfig to do the configuration for you The macro comes with options for all possible settings of the SKB This slide describes all options and shows their default value Please note that the SKB can currently not handle inputs from directories outside the root hierarchy However one can call skbconfig anytime to change the root directory but be carefull with potential side effects 16 User Manual oJojejeje Jeje Getting Started Configuration skbconfig Example variations for skbconfig default content of skb cfg skbconfig root doc fig figures sli slides acr database latex acrfile acronyn bib database bibtex bibfile bibliograhpy rep repository pub publish skb cfg fusing relative path for root and no directory structure skbconfig root rep pub fig sli acr acrfile acronyn bib bibfile bibliograhpy imyfile tex The macro skbconfig requires one argument which describes where the configuration has been changed This is helpful in combination with the macro skboptionsused to trace configuration
12. The SKB User Guide Sven van der Meer Wednesday 4 August 2010 Contents The TEX SKB Package csi uds be ee e ee Ee ee e ee ews 2 1 1 The Idea 40000 ee Be ets es a RO ae eas a By ee es amp a Rw a ee te See ee 2 1 2 The Story y mea eB A e E e a ee a 5 1 3 The underlying Concept 2 2 e 8 User Manual suma ee ES Bee EU ee RE ee E 13 2 1 Getting Started cia be ewe Eee bo he bee we ee de ee 13 2 2 Headings Files Figures Slides Paths Acronyms and References 21 2 3 Other usefull Macross s 2 2 25 6 ee ee a eee ee ee Pek ee ee a eee es 28 Examples 2 4 456 4 000 oo Bee ee hee bee ee ee Ee OR eee ew ee be 33 3 1 A simple Article ee 33 1 The ATEX SKB Package 1 1 The Idea The IATEX SKB Package ol 1010 The Idea The ATEX SKB Package This package provides macros that help to build a repository for long living documents It focuses on structure and re use of text code figures etc The basic concept is to first separate structure from content i e text about a topic from the structure it is presented by and then separating the content from the actual published document thus enabling easy re use of text blocks in different publications i e text about a protocol in a short article about this protocol as well as in a book about many protocols all without constantly copying or changing text As a side effect using the document classes provided it hides a lot of LaTeX from someone
13. They are pre configured and will be automatically set unset according to the three main document types the SKB supports text is equivalent to any classic text document for instance an article or a book slide is used to idenify slides for instance beamer frames note is used to identify lecture notes or handouts in essence annotated slides frames anim for beamer frames used for text with animation activated noanim for beamer frames used for text with animation deactivated memoir used for documents that include the memoir package We use the packages versions and optional and support both The main difference is that with versions one has to use beging and end while with optional one can use more than one of the above introduced types The macros for provided for optional text are skbmodetext and options using text will be valid if neither beamer nor beamerarticle is loaded normal text skbmodeslide and options using slide will be valid if the beamer package is loaded slides skbmodenote and options using note will be valid if the beamerarticle package is loaded annotated slides skbmodeanim and options using anim will be valid if the beamer package is loaded and the SKB is loaded with the argument beameranim skbmodenoanim and options using noanim will be valid if the beamer package is loaded and the SKB is loaded with the argument beamernoanim skbmodememoir and options usi
14. afe a lot of time demands archiving of published documents thus creating a traceable history helps to keep important information updated without jeopardising any other work and prevents losing any stufP The repository needs a few rules a customisable structure but beside that only a bit of effort to be maintained To give an example while writing the first version of this article May 11 2009 I have moved 4 lecture notes 2 presentations 1 book chapter 1 book in writing 1 textbook for students with 4 chapters and 4 articles from my mess into my repository This involved some re formatting plus the occasional re drawing to bring the original sources into the target formats At the same time I did develop the rules of my repository the structure and the mostly TEX code and re wrote structured ruled most of them a few times I ended up with 1 314 files in 87 folders which create 9 articles 2 books 1 textbook 3 lecture notes and this document note the number of articles increased because 1 could re assemble stuff for new uses spending some five minutes per one new article I did remove roughly 100 pages of text take the classic Spring LNCS format and you get the point of the number of characters and some 40 figures all duplicates I did find way too many errors in the original sources most of which have been created by re using them earlier from even more original sources 1 3 The underlying Conce
15. cluding list of acronyms It is very similar to BIBTEX 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 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 figures and combine acronyms and BIBT Xin a folder called database separating the data from all other content This slide shows the resulting directory structure 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 2My figures are exclusively in SVG using inkscape www inkscape org This has the advantage of a standardised text based format with many export options All my figur
16. e default for the author is an empty string The macro skbsubject will set the subject information to be used for PDF info The default for the subject is an empty string The macro skbkeywords will set the keywords to be used for PDF info The default for the keywords is an empty string The macro skbpdfintfo will call the macro pdfinfo to set the meta information in the created PDF output file The SKB automatically calls this macro just before finishing the process of the main document using the information provided by the above described macros Furthermore the date of the PDF file will be set 31 User Manual 010101010 Other usefull Macros Optional Text Versions and Optional Supports the packages version and optional o Comes with 6 defined modes automatically configured text normal text e in an article slide slides i e beamer frames note annotated slides e beamerarticle anim noanim animated and non animated slides frames memoir used when memoir package is loaded opt text The following example opt note This slide shows some examples for optional text optional package begin skbmodememoir Only with memoir end skbmodememoir opt anim skbfigure multiinclude myfigure opt noanim skbfigure width textwidth myfigure Optional Text Versions and Optional The SKB provides two means to include text and other ATfXcommands on an otional basis
17. eat twice pdflatex user guide ug slides notes repeat twice remove all files except the PDFs for cleanup Rebuild the SKB from Source The SKB class and style files as well as the documentation can be rebuild from its sources very easily The class and style files are part of the documented 4TpXsources in the file source skb dtx and the ETFXinstaller source skb ins provides all necessary instructions Simply follow the steps shown in the first part of this slide All you have to do then is to copy the files created to your ATEX distribution The SKB documentation comes in several different ways The file source skb dtx contains the docu mented source while the files in doc user guide can be used to generate the User Guide without source documentation the SKB presentation animated and not animated and the lecture notes for the presen tation When processing the file source skb dtx the User Guide will automatically be included in the generated PDF if it is found in either of the directories source doc user guide when using the SKB original distribution or source doc latex skb user guide when the SKB is already installed with your ETFX distribution The second part of this slide shows how to generate the complete SKB documentation Please note that the sequence is partially important for instance the file ug slides noanim must be processed before the file ug slides notes Please note that the SKB documentation is heavily u
18. ed Class and Style Files A O Eon The global Configuration File EAN raro oder tty sate tiene etapa see tert The Style File SHG Mies O E a A The Class Files ME o dae ae a ONE Deco The Source files LA a O SE Documented MTpXSource File A ia riers TE E The ATgXInstaller File E CEE SA RARO Manifest Licence Todo List and History as plain Text The SKB Distribution The SKB distribution that one can download from SourceForge or CTAN CTAN coming soon contains the source files for the SKB the generated classes and styles the generated documentation and the source files for the user guide This slide shows the structure and content of the SKB distribution 13 User Manual foley 1010101010 Getting Started Installation First e Go to your lAT Xdistribution Classes and Style Files o Create a folder tex latex skb Copy run into that folder tex latex skb Update filename database of your lATEXdistribution Documentation o Create a folder doc latex skb e Copy doc into that folder doc latex skb Source o Create a folder source latex skb Copy source into that folder source latex skb Installation There are two ways to install the SKB The first option is have it automatically installed by your IAT X dis tribution using T XLife or the CTAN archive The second option is a manual installation doing the following steps 1 Go to your TeX distribution to the folder tex latex 2 Create a folder s
19. ed in many research proposals and projects and created tons of notes and figures As of early 2009 most of that information was distributed over the repositories of different projects and organisations I worked for in some document management systems on several websites databases my preferred email client which changed twice different computers and later even different external hard drives and USB sticks Looking for specific text or a particular figure could easily end in a days work Tools like desktop search engines can help to find stufP I used them but if they found anything it was hard to maintain the context it was written in and some formats or sources were out of reach for them Even worse with figures and the many versions some of them evolved in over time After multiple jobs and several years all I had is kind of a very messy base of knowledge well hidden somewhere thus very difficult to locate and impossible to maintain So I started early 2009 to re organise my stuff At the same time I did realise that moving away from ETfXwas part of the problem and I thought using the other text processor would help it actually didn t long term So IATfXbecame again the text processor of choice and with it the ability for a complete different approach to organise my stuff This was the moment the SKB was created SKB stands for Sven s Knowledge Base The Tf Xpackage skb described in this article forms part of a larger software s
20. ent system subversion perforce systems web servers email clients The problems associated to this situation are manifold Ideas concepts are hidden often un accessible and as I experienced search tools are of limited help The documents are written in all sorts of formats or available only in usually proprietary binary formats Ever tried to open a document written in MS WinWord 6 0 with customised document template in a newer version of the same programme You know then what I am talking about Reusing the ideas concepts once found in a document and managed to open that very document usually involves huge amount of re formatting This will produce mistakes Ever tried to use a BIBTEX generated reference list found in a PDF file in a new article I found better ways to spend my nights and weekends yes I am married and I have a garden Over time it can become very difficult to distinguish between different versions of a document concept and or idea As it happens in real life things move on even in computing and the related sciences Documents are written for a specific historic context which might but often will not appear in their abstract or the name of the folder their are stored in The above issues do apply to figures and presentations as much as to the text part of documents Reorganising my documents figures presentations I did find way too many duplicates I have used too many graphic software packages in the past 10 years w
21. eparator and the argument provided 26 User Manual 0101010101010 Headings Files Figures Slides Paths Acronyms and References Acronyms and References Load Acronym Database o skbacronyms will load the Acronymnym Database e Should be called right at the place you want to have the list of acronyms printed Load References o skbbibtex will load the reference list e Should be called before starting with the document Loading Acronyms and Bibliographic Information These two macros can be used to load the acronym database skbacronyms and the references skbbibtex Both macros behave identical they use InputIfFileExists to check whether the acronym or bibtex file exists If so they simply input the file If not they use PackageError to throw an error with a help message showing the requested database file to input One should use skbacronyms at the place in the document were the list of acronyms should be printed and skbbibtex at the beginning of the document to load the bibliographic information 27 2 3 Other usefull Macros User Manual e Jejejeje Other usefull Macros Emphasising Text ATEXexample for skbinput Use cmd skbem to produce skbem bold bold skbem italic italic or skbem code type writer text The example above shows the macro skbem code skbem with the option skbem italic bold and skbem bold italic And the result Use skbem to produce bold
22. epts with regard to data encoding protocol message formats protocols themselves and protocol services The last block loads four files with headings categorised as sections Using the directory names we see that the remaining article describes the protocols GIOP defined by the OMG SNMP by the IETF CMIP by the ITU T and finally HTTP by the W3C Finally we load acronyms and bebliography and finishing the article This example will create a table of contents similar to this il co En A sd a a OG A SG al oil A aa 5 e so 695 000002 200 2 1 2 MERO POROS 5 6 5 6 6 2 6 4 6 ue 5 LDPE TOCOL e a iG eG A a A S 7 ImaRPbrot o coser E 9 2 General Tnper 0ORB Protocol o o a S a a e s r sa w o y 10 3 Simple Network Management Protocol 13 4 Common Management Information Protocol 15 5 Hypertext Transport Protocol aana a 18 Job done Now we can use TEX or PDF BTFX to compile our article 33 Examples eje Jeje A simple Article An Example Article TEX code Example loading inital text skbinput from rep sota protocols Example a section called Introduction section Introduction skbinput from rep level subsection sota protocols data_encoding skbinput from rep level subsection sota protocols message formates skbinput from rep level subsection sota protocols protocols skbinput from rep level subsection sota protocols protocol servic
23. er already e Changes in the repository will potentially effect multiple documents These changes are not neces sarily intended or wanted I e if an article a book and a beamer presentation access the same source code example a change here might have a negative effect on the beamer presentation Similarly if text is changed it might have a negative effect on lecture notes or annotated beamer slides e Versioning the repository text and figures is very difficult e Cross references need to be used carefully since a repository file cannot assume that the master document uses the other file referenced The SKB provides no solution for this at the moment though I have some ideas 1 2 The Story The IATEX SKB Package el 1010 The Story The Story short version After 10 years writing documents and not maintaining them properly o My stuff got distributed in multiple dimensions e Some hidden in emails on shared discs external document systems web sites Finding anything became almost impossible e Tried many tools none really helped to organise my mess Early 2009 decided to reorganise everything o Well defined set of tools applications PHP ATEX BIBTEX Inkscape SQLite Java o Then started writing the ATEXpart for the SKB This now became the SK Bpackage The Short Story I have written papers done a lot of presentations provided some book chapters still working on a book participat
24. es Examples ejeje Jo A simple Article An Example Article TEX code Example more sections skbinput from rep level section sdo omg corba giop skbinput from rep level section sdo ietf snmp protocol skbinput from rep level section sdo itu x700 cmip skbinput from rep level section sdo w3c http Example finishing the tex file end document endinput 34
25. es 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 3Now the reason for the database folder and it s structure is that the whole SKB contains more databases all of which reside here If you want to simply apply this to IAT Xdocuments you might want to use a different strutural approach 10 The IATEX SKB Package ojejeje 10 The underlying Concept Separate Parts of the Document Part Publications and Content Now look into published documents there are different types e Articles Books Lecture Notes Presentations The Folder publish your repository root path to your repository like dev documents lL ssl LMA cocoon oosbouescogosososcc0c0e0DNND folder for published documents articles cate aan aero noes cnr A S anos oo meee such as articles DOOK SE e A ea os or books lecture notes ron en a a a or lecture notes for computer science presentations te or general presentations Esd I Fece Publications and Content Part II 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
26. esize it i e to the width of the text in your document putting this very box into a figure environment so that TX can process list of figures etc and of course adding lable and caption to it The first block of this slide show a ATEX example which also uses the center environment With the SKB macro skbfigure things become a little bit simplier takes a number of options and one argument The second block on this slide shows a number of examples for using this macro skbfigure myfig skbfigure figure center myfig skbfigure figure center width textwidth myfig skbfigure figure center caption My Figure label myfig myfig oRWNF Let s start with the easy usage simply using the one argument to load a figure as shown in line 1 This call will simply use includegraphics and resizebox to load the figure myfig from the figure directory so we do not need to say figures anymore To use the figure and the center environment we simply add two options requesting exactly that as shown in line 2 In other words using the option figure will put the myfig in a figure environment and using the option center will center the figure Similar for width and height information Say the figure should be rescaled to the width of the text in your document you simply add width to the options as shown in line 3 Use height for height or both options if required Note that the width and the hight are automatically applied to the r
27. esizebox and includegraphics You can also add caption and label information using the respective options lines 4 and 5 Now we will have the same result as the classi TX example You can also add the required position for your figure if using the figure environment applying the option position with the usual paramters including H from the float environment 22 User Manual 01010 10101010 Headings Files Figures Slides Paths Acronyms and References Options for skbfigure width Set the width to be used with resizebox and includegraphics height Set the height to be used with resizebox and includegraphics center Use center environment figure Use figure environment position The position to be used within figure environment This option will be ignored if not combined with figure caption The caption to be used Ignored if the option figure is not used label The label to be used Ignored if the option figure is not used multiinclide The label to be used Ignored if the option figure is not used Figures Multiinclude The last option for the macro skbfigure is called multiinclude It can be used with the beamer package to realise animations by loading a series of images and showing them in sequence with or without overlaying If used this option will overwrite all other options resulting in a simple call to multiinclude within a resised box One can use all standard multiinclude paramters with skbfigure just o
28. graph List styles SKB specific environments adding specific behaviour to lists and enumerate environ ments Listings basically a few pre defined styles for using the listing environment PDF Info some macros that help to set meta information in PDF documents Acronyms some macros that help to load the acronym database and more BIBTEX one macro that loads bibliographic information For the impatient we start with a few examples The first one shows how to use the SKB to produce a simple article The second one exmplains how the documentation for the SKB is created using most of the SKB macros Then we detail the usage of all the macros following the above introduced categorisation 20 2 2 Headings Files Figures Slides Paths Acronyms and References User Manual 0 Jolejelejele Headings Files Figures Slides Paths Acronyms and References Headings and Files skbheading skbheading My Heading skbinput myfile skbinput from rep myfile skbinput from pub myfile skbinput level chapter myfile skbinput from pub level chapter myfile skbinput from pub test myfile OoRWNEFH from pub rep fig sli level book part title chapter section subsection subsubsection Files and Headings Just to remember we have two different types of files in two different directory structures The repository folder stores the content and the publish folder stores everything needed
29. helpful if you o Need to organise large amount of stuf o Want to reorganise stuff e Plan to maintain a personal repository The SKB has side effects and cannot do coffee for you either o Separating content from structure makes content almost context free Changes in content effect potentially multiple documents of different type Versioning and change logging becomes almost impossible Your style of writing documents might need to change e Cross references between parts of stuff need to be used carefully Applicability and Side Effects The SKB can help you if e You have too many concepts and ideas spread over too many places e You want to re organise all of your stuff e You plan a personal repository or a well maintained document base for a single purpose It will be difficult to use the SKB for a widely distributed repository that is not well maintained since there are side effects that might run out of control The SKB has side effects which might cause problems e Separating contents from structure see below means that the contents needs to be almost context free Since we can assemble any contents into anything a book an article we need to write self contained text That can be very difficult and lead to documents that do not give the reader the impression of a consitent and coherent story However carefully writing can avoid that problem and I am sure you are carefull writ
30. hich don t exist anymore or which do not run on the latest version of my preferred operating system Some of the figures are only available in some sort of low resolution bitmap rendering them useless even for a non peer reviewed article today the original source got lost in most cases because someone removed the project folder after the project was terminated The IATEX SKB Package ojoje The Story The Story long version Part II Solution Create a unified document repository Then use it as source to generate documents o Leave text heading text figures etc in the repository o Helps to keep information updated no more copy and paste e Only a few rules little effort for maintanance An Example from 2009 first version of the SKB Moved 4 lecture notes 2 presentations 1 book chapter 2 books and 4 articles o Created 1 314 files in 87 folders but e Removed about 100 pages of douplicated stuff e Removed many many duplicated figures e Also found tons of errors from re using already reused stuff The Long Story Part II A solution is to create a unified document repository then use this repository as normative source to create documents for specific purposes while leaving the text blocks headings figures presentations references acronyms and all other reusable stuff in the repository for the next document which might hopefully will benefit from them This can did it for me already s
31. igures lao Ropa E E aannaAnh or for instance doc Sis folder for all sorts of data for the repository WI O O ACA aO ao data in ATEX such as our acronyms eee onl O Enon On eeS BIBTEX database IL Los oll Ue folder for figures my sources are SVG PDF l Eo ood IPPO Ste E E folder for the text files LL Eo od Bibliography Acronyms and Figures So the combination of 4 TfXand BIBTEXalready 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 BIBTEXand process them with the biblatex package but that is not critical for now My BIBTRXdatabase is in a special folder we can call it references for the moment and it uses a file structure that helps me to find information This structure is based on the BIBTEXand 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 figures for the moment which contains the source of the figures and the generated formats I need for my documents usually PDF some PNG Now I can reference these figures from the repository as well as for other use cases such as web publishing or presentations Last not least the acronym package allows for an automatic handling of acronyms in
32. ind 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 sdo and the sub folders using the respective SDO acronyms such as omg for the OMG and ieee for the IEEE and 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 This slide shows how that looks like 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 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 The IATEX SKB Package jejeje Jeje The underlying Concept Separate Parts of the Document Part o Create a folder for data e Acronyms References o Create a folder for figures Bibliography Acronyms and F
33. kb 3 Copy all files from the directory run of this package to the newly created folder tex latex skb 4 Update the filename database of your XIX distibution Please see the manual or help files of your TEX distribution for details If you want copy the source and documentation files as well then do the following steps We start with the documentation 1 Go to your TeX distribution to the folder doc latex 2 Create a folder skb 3 Copy all files from the directory doc of this package to the newly created folder doc latex skb And now the source files of the SKB 1 Go to your ATEX distribution to the folder source latex 2 Create a folder skb 3 Copy all files and directories from the directory source of this package to the newly created folder source latex skb Now you have installed the SKB and you are ready to use it 5Note This option is not yet supported since the SKB has not yet been submitted to CTAN 14 User Manual oloro Jejejeje Getting Started Rebuilding the SKB Class Style Files and Documentation Rebuild Class and Style files cd run latex source skb ins gt creates skb cfg skb sty skbarticle cls skbbook cls skbbeamer cls skblncsbeamer cls and skblncsppt cls Rebuild Documentation cd doc pdflatex source skb dtx repeat twice pdflatex user guide user guide repeat twice pdflatex user guide ug slides anim repeat twice pdflatex user guide ug slides noanim rep
34. mit the enclosing brackets For instance if you want to use multiinclude on the myfig with the options lt gt call skbfigure multiinclude myfig The figure size will be automatically set to textwidth and the height to The start of the multiinclude is fixed to be 0 the format is PDF For more informatio on how to use multiinclude please refer to mpmulti and beamer packages 23 User Manual 0101010 101010 Headings Files Figures Slides Paths Acronyms and References Slides Use skbslide and skbslidecite to integrate slides from outside the ATEXuniverse Load PDF slides with or without ATEXannotations Load the PDF and or the ATEXfrom any SK Bknown path e Add standardised citation for the slides to the annotation Example with Microsoft Powerpoint o Take a Powerpoint presentation and print all slides into a 4x3 format individual PDFs Write or reuse existing anotations using IATEX and BIBT Xetc e Produce handouts using the SKBand present the slides using Powerpoint Slides This macro helps to create lecture notes handouts using PDF slides and TEX notes without using the beamer package The reason for adding this to the SKB was to integrate slides from sources outside the IXTFX universe i e Microsoft Powerpoint Some of my presentations are done using Powerpoint but for handouts I do prefer using ATEX thus benefiting from many of the automated features it provides references acrony
35. ms As a nice side effect the output generated is scalable assuming that the PDF sources of the slides contain scalable images rather than bitmaps which can be easily realised using for instance Inkscape s EMF export within Microsoft Powerpoint slides The macro skbslide provides all means to include PDF slides with or without annotations annotations only and it can load the annotations using different mechanisms The macro offers two options to set the input path for the slides and the annotations slidefrom and notefrom If slidefrom is used then the slide PDF file will be loaded from the requested path sli rep or pub If notefrom is used then the annotation TEX file will be loaded from the requested path sli rep or pub The default path for slides and annotations is the path for slides The third option annotate requests to load annotations If not used no annotations will be loaded It can be used in combination with the two arguments to automated loading annotations The two arguments of this macro define the files for the slide and the annotation They can be used as followes e Argument 1 is the slide to be loaded If a name if given we load the PDF using inputgraphics with width being textwidth If no name is given no slide will be loaded e Argument 2 is the file with the annotations in combination with the option annotate If this option is not used then no annotations will be loaded If the option is used and no name
36. ne numbers e genericLN same as generic just with line number in the left side which means allowing extra space left to the listing box gentab almost the same as generic but without definitions for frame and numbers which seem to collide with some table environments e genericLNspecial same as genericLN just with a lighter grey for the box e beamer example style designed for examples in beamer frames beamer exampleLN same as beamer example just with line numbers on the left which means allowing extra space left to the listing box e javaCode generic style plus lanugage Java There is also one macro supported which sets the listing style back to normal i e after changing it in the text Some macros in the SKB make use of this All that lstdefinestyle does is setting the basic style back to type writer font 30 User Manual 0101010 Je Other usefull Macros Macros for PDF Info Macros to set information call them anywere in your document o skbtitle the title o skbauthor the author skbsubject the subject o skbkeywords the keywords e date will be set automatically to today SKB automatically calls the skbpdfinfo macro at the end of the main document Macros for PDF Info The macro skbtitle will set the title to be used for PDF info The default for the title is an empty string The macro skbauthor will set the author information to be used for PDF info Th
37. ng memoir will be valid if the memoir package is loaded This slide shows a few examples on how to use the optional text 32 3 Examples 3 1 A simple Article Examples el Jejeje A simple Article An Example Article TEX code Example start of the tex file documentclass skbarticle begin document author Sven van der Meer title Protocols Formats and Communication Services maketitle tableofcontents bigskip A Simple Article Take the article that describes the state of the art in protocols Remember we have all the contents for that in our repository directory We go the directory that has the published articles published articles and create a new file say protocols tex as shown on this slide and the following two slides The article uses the class skbarticle That class will load the SKB package and the memoir class and do all settings we need It prepares the title page and prints the table of contents like any other 4 TpXarticle The it uses skbinput to load files from the repository The first one is loaded without requesting a level In other words there is some text right at the beginning of our article without any special heading like an abstract Then we do start the section Introduction and collect a few files with their heading categorised as sub sections Reading the directory and file names we can already guess what the introduction will be doing it introduces general protocol conc
38. pt The IATEX SKB Package e Jejejeje The underlying Concept The Concept Separate Things Separate as much as you can but not more o Separate content of a document from its structure e Identify small coherent blocks of information Put them in a separate folder the repository o Separate the different parts of a document Documentation reason publish from repository e Code figures examples acronyms references 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 1 separate content of a document from its structure and 2 separate the different parts of a document For the impatient 1 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 2 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
39. r document base The publish folder contains documents that are published for a reason i e articles books presentations white papers work in progress while the repository folder contains content most likely structured following a content specific categorisation The choice of how the directory structure looks like is yours and of course you could also have multiple document directories with completely different structures for instance one for computer science publications and one for a gardening book The SKB does not set any limit since it can be configured very flexibly to your needs 19 User Manual The SKB provides macros that simplify file handling and hide some TEX code i e for figures from the user thus helping everyone to focus on the actual document one wants to write There are a few macros and they can be catagorised as follows Files and Headings skbinput and skbheading are used to load files and manage the headings of documents i e associating a heading with a level in the document structure section subsection etc Figures skbfigure is your Swiss Army knife for loading figures and graphics Path and filenames these macros provide direct access to SK B managed paths and filenames Input files here we have a few macros that load tex files figures slides and slide annotations Emphasising text some macros that deal with typesetting text in different ways to emphasise that text from the surrounding para
40. repository older It also means to build a separate repository for figures since they could be used in many different small blocks of information The IATEX SKB Package e10 Jejeje The underlying Concept Separate Content from Structure LSpositor renee errr cere ee tree etc ree the Repository Folder EES ALORA EE O vano the folder with our SDO files M ONE a E a E E E EEE E E es files for OMG stuff A ee eet The CORBA IDL language ada Fs aa a The OMG Model driven Architecture LL Paad E o ARROCES ee MRS econ files for IEEE stuff O oi The IEEE LAN concept OLAS nd a A The Ethernet protocol IL Po ood ET E e NOAA OO os files for IETF stuff EA Aro ROO ne The DNS protocol IA o AA aio Aaa The URI specifications Le Hoc LL Eosed lL Eoso 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 We collect sentences and paragraphs but separate them from headings IATFXis 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 setheading This allows to select the appropriate TpXheading level at a later stage having the context of that later stage in m
41. s automatically called at the end of processing When creating the documentation for the SKB by running pdflatex skb dtx the following output will be created Package skb Warning Options last changed by skb presentation skb Change log skb root skb sty ug slides noanim tex skb acr skb sty skb acrfile skb sty skb bib skb sty skb bibfile skb sty skb rep skb sty skb pub skb sty ug slides noanim tex skb fig skb sty skb sli skb sty skb presentation skb Last set Path File Options skb file root user guide skb path root user guide skb file acr user guide database latex acronym skb file bib user guide database bibtex bibliography skb path bib user guide database bibtex skb path rep user guide repository skb path pub user guide skb path fig user guide figures skb path sli user guide slides The change log shows that all configuration options have been set by skb sty and later by skb cfg Furthermore the configuration option root has been changed by skb dtx 18 User Manual oJojejeJejeje Getting Started Creating a Directory Structure The Directory Structure used in this Guide your repository root path to your repository like dev documents database tao tet folder for all sorts of data for the repository latex this is were MTpXdata will be collected
42. sing the SKB macros so you will need to have the style and class files installed before you can rebuild the documentation 15 User Manual 0101010 Jelele Getting Started Configuration Options root Sets the root path of the SKB Everything that the doc SKB processes should be located below the root pub Sets the path for the published documents publish rep Sets the path for the repository documents repository fig Sets the path for figures figures sli Sets the path for the slides transparencies acr The SKBuses the acronym package and these two macros acr acrfile dtail the directory acr and the file acrfile where the database latex acronyms can be found acrfile acronym bib These two macros detail the directory bib and the bib bibfile main file bibfile where bibliographic information database bibtex BIBTEX database can be found bibfile bibliography There are multiple options to configure the SKB The following list contains all possible options starting with the least significant That means that the higher priority settings which overwrite other settings will be listed at the bottom e Change the file skb sty in your TpXdistribution This might require administrator root privileges This option while possible is not recommended e Change the file skb cfg in your 4 TpXdistribution This might require administrator root privileges This option is suitable for a system wide configuration say on
43. skbfilepub with 1 argument the publish dir 1 skbfilefig with 1 argument the figure dir 1 skbfilesli with 1 argument the slide dir 1 skbfileroot examples skbem skbfilfig dirtree complete Path and File Names The SKB provides a number of macros to directly create path and file names Most of these macros are actually used within the SKB but they might also be useful for users to access files without using the provided specialised macros such as skbinput The following macros are provided skbpathroot returns the set root path of the SKB skbfileroot returns the set root path and adds 1 i e the directory separator and the argument provided skbfileacr returns the path including root and file name for the acronym database skbfilebib returns the path including root and file name for the file that loads the reference database BIBTEX skbpathbib returns the path including root to the reference database skbfilerep returns the path to the repository and adds 1 i e the directory separator and the argument provided skbfilepub returns the path to the folder with the published documents and adds 1 i e the directory separator and the argument provided skbfilefig returns the path to the figure folder and adds 1 i e the directory separator and the argument provided skbfilesli returns the path to the slide folder and adds 1 i e the directory s
44. such as our acronyms LD e e E folder for all BIBTEX reference files I figures o n ete a aii folder for figures my sources are SVG amp PDF pubis he a E folder for published documents AAC a a a A E E A oars such as articles ME ID OO a E A AA E A T E O T or books I Tecturesnovesninnussscsty A eee or lecture notes for computer science e presentations aasre r ista ete or general presentations POS AS E E R e E folder for the text content Creating a Directory Structure The real power and possibly madness of the SKB comes with the separation of different parts of a document into different directory structures For the user guide we assume the general directory struc tureshown in this slide To create this structure go to the directory were you want to put all your documents say doc Now create the folders database figures publish and repository and the respective sub folders as shown in this slide Finally configure the SKB by either editing one of the configuration files or adding the following line to all of your published documents and of course change the text myfile tex to something that tells you about the location of the configuration change skbconfig root doc acr database latex acrfile acronym bib database bibtex bibfile bibliograhpy rep repository pub publish fig figures sli slides limyfile tex The directory structures for the publish folder and the repository folder reflect different views to you
45. t for replacing itemize skbnoteenum for replacing enumerate Both do nothing but chaning itemsep and parskip Set to 0 o Same effect as tightlist in the memoir package Both enviroments do nothing if the memoir package is used Environments for lists and enumerates These two environments mimic the macro tightlists from the memoir package It might be usefull when not using memoir to minimise the margin between items in lists iemize and enumerations enumerate Both environments do the following e Store current value of parskip and itemsep e Set parskip and itemsep to Ocm e Use the original environments itemize for skbnotelist and enumerate for skbnoteenum e Set parskip and itemsep back to thir original value Here is an example using first the classic list environment itemize and then the SKBmacro skbnotelist e Lorem ipsum dolor sit amet consectetur adipisicing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua e Ut enim ad minim veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat e Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur e Excepteur sint occaecat cupidatat non proident sunt in culpa qui officia deserunt mollit anim id est laborum Now list with skbnotelist e Lorem ipsum dolor sit amet consectetur adipisicing elit sed do eiusmod tempor incididunt ut labore et dolore magna aliqua
46. will trow an error To associate a document level for the heading we can use the option level to define which level we want This option understands all standard document levels from the memoir package book part title chapter section subsection and subsubsection So if we want to load myfile tex as a chapter we simple invoke skbinput as shown in line 4 of the example Since myfile tex is part of the repository we combine the two options from and level see line 5 This call to Ninput will load myfile tex from the repository and use chapter for the heading found in that file If myfile tex is in a sub folder we simply add that sub folder to the filename An example is shown in line 6 assuming the the file is located in the repository sub folder examples 21 User Manual foley Jelejejele Headings Files Figures Slides Paths Acronyms and References Figures Classic ATEX Example begin figure begin center resizebox textwidth includegraphics width textwidth figures myfig caption My Figure label myfig end center end figure skbfigure 1 skbfigure myfig 2 skbfigure figure center myfig 3 skbfigure figure center width textwidth myfig 4 skbfigure figure center caption My Figure label myfig myfig Figures The classic way to add figures to your document is to have a PDF or PNG or JPG file ready include it using includegraphics while putting it into a box to r
47. ystem that uses SQLite databases a small PHP framework Apache for HTML access and recently also a Java port My document repository uses the skb package so most of my documents are eventually TpXdocuments I am saying eventually because I still use other tools like Microsoft s Powerpoint but integrate their output in my repository I do all my figures these days using Inkscape so the source is SVG and the output for 4TRXdocuments PDF For editing the text files I do flip between UE Studio and LeD Parts of the content such as acronyms and bibliographic information are maintained in SQLite databases and exported to TEX This package now shows how I build my documents The IATEX SKB Package eror Jo The Story The Story long version Part The Problems was facing Ideas concepts hidden and unaccessible Many documents in many different formats o Reuse of stuff requires lots of work and involves copy and paste o Many different versions of very similar stuff no time for maintenance Same for text figures examples tables lists acronyms references all created stuff The Long Story Part I Over several years of writing documents articles books reports standards research proposals ideas and concepts became distributed actually a euphemism for hidden within many many documents in all sorts of formats located at many many locations such as local file system document managem
Download Pdf Manuals
Related Search