Documentation With Open Source Tools·(ასლი)
-
Upload
rashad-aliyev -
Category
Technology
-
view
743 -
download
1
Transcript of Documentation With Open Source Tools·(ასლი)
![Page 1: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/1.jpg)
Documentation with OpenSource tools
David Avsajanishvilifor BarCamp CaspianBaku, 2009
mailto:[email protected]
![Page 2: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/2.jpg)
Documentation is…
… the process of building communicable materials (text, tables, diagrams, etc.) to describe some knowledge:
Scientific and Technical documentation; Legal documents, reports, books, articles,
etc.
![Page 3: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/3.jpg)
Traditional approach:
WYSIWYG; Using word
processing editors; Using publishing
systems.
![Page 4: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/4.jpg)
Tra
ditio
na
l ap
pro
ac
h: E
XA
MP
LE
![Page 5: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/5.jpg)
Traditional approach: Disadvantages
![Page 6: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/6.jpg)
Traditional approach: Disadvantages Lack of clear
structure
![Page 7: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/7.jpg)
Traditional approach: Disadvantages Lack of clear
structure WYSIWYG:
WYG is WYS only!
![Page 8: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/8.jpg)
Traditional approach: Disadvantages Lack of clear
structure WYSIWYG:
WYG is WYS only!
Problems with version-tracking
![Page 9: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/9.jpg)
Requirements:
![Page 10: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/10.jpg)
Requirements:
Structurability
![Page 11: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/11.jpg)
Requirements:
Structurability Splitting content
and presentation
![Page 12: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/12.jpg)
Requirements:
Structurability Splitting structure
and presentation Reusability
![Page 13: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/13.jpg)
Requirements:
Structurability Splitting content
and presentation Reusability Version tracking
possibility
![Page 14: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/14.jpg)
Presentation Formats:~electronic~ HTML / XHTML + CSS WML Derived/related formats:
HTML Help, Wiki, etc…
![Page 15: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/15.jpg)
Presentation Formats:~printable~ PDF TeX / LaTeX / ConTeXt... PostScript, DVI XSL-FO
![Page 16: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/16.jpg)
Presentation Formats:~universal~ DOC RTF OpenDocument
![Page 17: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/17.jpg)
![Page 18: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/18.jpg)
Structure format: DocBook
Based on XML/SGML DTD Schema Maintained by OASIS technical committee Suitable for defining Books, Articles,
Chapters, References, etc. http://www.docbook.org
![Page 19: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/19.jpg)
DocBook: Conception
![Page 20: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/20.jpg)
DocBook: Conception
![Page 21: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/21.jpg)
DocBook: Example
![Page 22: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/22.jpg)
Idea: make easily editable “Document
structure” format
![Page 23: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/23.jpg)
Plain-text-based syntax for Documentation – ASCIIDOC Wiki-like plain text syntax Fully compatible with DocBook Could be converted to various Presentation
Formats through DocBook Could be converted directly to HTML http://www.methods.co.nz/asciidoc/
![Page 24: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/24.jpg)
AsciiDoc: Conception
![Page 25: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/25.jpg)
ASCIIDOC: Example
![Page 26: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/26.jpg)
ASCIIDOC: Example
![Page 27: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/27.jpg)
AsciiDoc SYNTAX
Document is started with Document Header Doucment consists of Sections, ranged by
Levels. Sections starts with Section Header (title)
Section consists of Paragraphs and Special Blocks (notes, warnings, numbered and labeled lists, tables, etc.)
![Page 28: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/28.jpg)
AsciiDoc:SYNTAX
![Page 29: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/29.jpg)
AsciiDoc:SYNTAX
![Page 30: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/30.jpg)
AsciiDoc USAGE:
Source could be converted to DocBook, HTML, PDF, PostScript ant other formats using command utilities;
Supports code reusing (composing doc-t from fragments using include::)
Output could be customized with command-line options and configuration files
![Page 31: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/31.jpg)
AsciiDoc FEATURES:Syntax highlight
![Page 32: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/32.jpg)
AsciiDoc FEATURES:GRAPHVIZ filter
![Page 33: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/33.jpg)
More complex example:
![Page 34: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/34.jpg)
Advanced Documenting:Batch script
1.Prepare source;
2.Make script for building documentation from the source;
3.Build different format output from single source using the batch;
4.Deploy documentation using the batch
![Page 35: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/35.jpg)
Advanced Documenting:Batch script
![Page 36: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/36.jpg)
Advanced Documenting:Auto-generating content1.Script file
![Page 37: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/37.jpg)
Advanced Documenting:Auto-generating content1.Script file
2.AsciiDoc source
![Page 38: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/38.jpg)
Advanced Documenting:Auto-generating content1.Script file
2.AsciiDoc source
3.Result
![Page 39: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/39.jpg)
Other tools
MediaWiki, Markdown, reStructuredText, Textile, POD...
Pandoc UMLGraph TextUML
![Page 40: Documentation With Open Source Tools·(ასლი)](https://reader034.fdocuments.in/reader034/viewer/2022042614/5588f642d8b42aa8418b45b2/html5/thumbnails/40.jpg)
Resources
www.methods.co.nz/asciidoc/ – AsciiDoc www.docbook.org – DocBook www.latex-project.org – LaTeX Project www.graphviz.org – Graphviz Project johnmacfarlane.net/pandoc/ – Pandoc
Project www.opendocs.info – Documenting portal