Documenting programs
At a certain stage of development of the software system, the task of developing user documentation inevitably arises. And here arises the technical question of choosing formats and documentation development tools.
With the choice of the final format, there are usually no problems, as the target operating system has its own requirements. For example, for programs for Windows, this is the format of CHM compiled help, for Linux and BSD systems, this is man. Common for all systems format for online help is html, and for printing - pdf.
The situation is complicated if it is necessary to have documentation in several formats - for distribution with the program (chm or man), for posting on the website (html) and for printing (pdf). It is possible that the content of the documentation in different formats may differ slightly. For example, it makes sense to include video clips in the online documentation, and in the print version they need to be replaced with a static image, possibly supplemented by qrcode links to the video fragment. In addition, the content of documents may vary for different categories of users, versions, delivery kits and other factors.
Despite the seemingly obvious need for the use of specially created programs, this is not so simple.
')
Approaches differ depending on the target operating system.
For example, to create compiled help for Windows in the chm format, Microsoft suggests using a special free HTML Help Workshop compiler. At the same time, source texts should be prepared in html format (editor is not included in the delivery), and table of contents files should be in a specific format. No means of forming printed manuals are provided.
Of course, specialized programs for creating help ( Robohelp , Help & Manual , HelpScribble and the like) provide a high level of service, have the ability to generate output documents in various formats and even to some extent profile the content.
However, they have the following disadvantages:
1.2.2. Simple Markup Formats
A rational alternative is the use of simple and, as a result, quickly mastered markup formats.
Today there are several such formats:
All these markup use some symbolic non-tagged set of rules for the designation of the heading, illustrations and links, which implies editing in simple text editors. Preparation of a viewable view is carried out programmatically, usually on the server side.
For example, Wikipedia converts a Wiki format to HTML on the fly. The web portal of the Git system http://github.org is also capable of displaying documents in Markdown markup in a form suitable for reading in a browser.
Despite the fact that there are enough notepad features to create and edit source texts, some service functions, such as spell checking and markup highlighting, would be very useful for a writer.
The article http://www.ixbt.com/soft/markdown-online-2.shtml provides an overview of online editors with support for markdown syntax, and http://www.ixbt.com/soft/markdown-online-3 .shtml provides an overview of the five desktop editors that support the default markdown format, out of the box, so to speak.
One of these editors is MarkdownPad .
Figure 1. MarkdownPad 2 editor
As can be seen from the copy of the screen, the MarkdownPad 2 editor supports a live preview of the edited file with support for synchronous scrolling of the source text and the result of rendering.
When installing on Windows 8, a situation may arise when the preview is not available.
Figure 2. Report crash preview system
According to the developers of http://markdownpad.com/faq.html#livepreview-directx, this is due to the need to install the Awesomium 1.6.6 SDK , a specific web rendering SDK , which in turn uses DirectX .
The editor supports syntax highlighting, syntax checking of one language (including Russian), export to HTML, PDF formats (only in the paid version). In other words, MarkdownPad 2, like other special editors, is a good choice for a technical writer. In the same cases, when the user has to edit files of various formats, you can adapt your editor for editing texts with markdown markup.
Notepad ++ can be considered an editor that adequately meets these requirements. Spell checking of many languages is supported using a special plug-in. And it supports text verification in several languages at the same time .
Figure 3. Notepad ++ editor
Despite the simplicity of the rules of markup, the author of the texts would be more convenient to work with syntax highlighting. With reference to Notepad ++, the project Markdown Syntax Highlighting for Notepad ++ will help, which, in essence, is the configuration file for the custom language Markdown. After installing it, the text in the editor looks like this.
Figure 4. Notepad ++ editor with markdown markdown elements highlighted
It is noteworthy that markdown editors even exist for mobile platforms. The figure shows a copy of the smartphone screen with the Quoda Code Editor running.
Figure 5. Quoda Code Editor - the universal editor for Android with markdown markup support
It should be said that most of this article is typed in this editor, and only then downloaded to the computer for revision.
Based on the analysis of the Markdown markup language and special editors, we can recommend their use for documenting systems of medium complexity.
However, for the development of software documentation for large systems, an open, well-documented format should be used as the source format. As a means of formation, it is a tool with extensive capabilities for customizing the appearance, profiling and the ability to generate documents in various formats.
Systems such as DITA and Docbook fully meet these requirements.
Despite some differences, both systems have much in common:
It should be emphasized that these systems use semantic markup in the source documents. The appearance of the output is determined by the rules and parameters of transformations. This approach allows the author not to think about typography and design at the stage of writing source texts, but to focus solely on the semantic content.
At the same time, the practical experience of using, in particular, the Docbook, confirmed in a number of publications , showed that there are some difficulties with using such a well-thought technology:
Naturally, the above disadvantages constrain the widespread use of XML-oriented single source technologies.
If you use non-tagged formats for preparing offline or printed documentation, you need to use conversion utilities. Among many converters, the pandoc program deserves special attention.
Pandoc is a cross-platform, command-line program that can convert texts in a wide variety of markup to multiple output formats.
For example, using pandoc, you can convert source documents in ASCIIdoc, Wiki, Markdown layouts to HTML. If you install LaTex, it becomes possible to receive and PDF.
For example, the conversion of the source text of this article into html format can be performed with the following command:
The result will be a ready html file:
Figure 6. HTML document formed from Markdown by the pandoc utility
For its versatility, the program is figuratively called the author of the "Swiss Army Knife."
Indeed, pandoc copes with converting without any loss of information. When converting from MarkDown format, it is possible to read three metadata parameters - title, author and date of the document. It also supports passing command line parameters to set some specific properties, such as the document language. It is possible to set your output template, modifying it to some extent.
For example, in the example above, it is assumed that in the current folder there is an h.html file that plays the role of the header. If we add a link to the style file in this file and, having defined
Figure 7. HTML document generated by pandoc using a header file with style links
As you can see from the example, the headings acquired their own style, and external links began to open in a new browser tab.
The above-described format capabilities make it justifiable to use Markdown markup to document relatively small software systems, for which no GOST requirements are required, which is proved by its wide use in the Git system.
As for large systems with extensive and complex documentation, for its creation seems to use the system of a single source Docbook. There may be transitional cases where the scale of the project does not appear immediately.
The difficulty of creating source XML sources can be overcome by using Markdown sources and converting them to a Docbook. This conversion is supported by the pandoc utility. So the team
will create the resulting file .
The use of the
Figure 8. The generated article in the XML editor
There are several additional markdown markup requirements that will be used to convert to a docbook:
First, you should avoid using angle brackets (<and>) in the text, since in XML they are used to extract tags, and the converter leaves them as is. If the angle brackets are needed by meaning, then you should use the entities
Secondly, when inserting a picture, it is necessary to enter alternative text, since pandoc uses it to create the required
However, the output text is formed in the obsolete Docbook 4 version format, while the modern 5 version provides significantly richer semantic markup features.
To convert text from version 4 to version 5, you can use the special conversion db4-upgrade.xsl included in the Docbook package.
Thus obtained xml file docbook 5 schema can be used when forming a single source.
Figure 9. Schema article in XML editor in author mode
The described chain of transformations may seem at first glance long and unnecessarily complex. However, once you have mastered the necessary tools and developed command files (scripts) for frequently performed tasks, you can save a considerable amount of time in the future.
It should be emphasized that the technology of a single source has a pronounced cumulative effect. The initial time spent on the development of typical reusable text fragments is paid off when they are used in subsequent projects. It is this quality that makes the technology of a single source particularly attractive when documenting serial software systems.
A set of transformations Docbook supports the formation of documents in HTML with styles, PDF for printing so to say "out of the box."
The appearance of the output can be configured to a certain extent using parameters. The resulting file format FO-XSL pandoc5.fo is intermediate and is needed to build the final PDF .
The possibility of automatically generating a table of contents, a list of illustrations, listings, tables, an index, a glossary of terms, and a list of references is also important.
With a large number of documents in the package, it is also possible to create a separate list with the possibility of automatically generating properly designed links to them. In the case of the preparation of a typographical layout of the manual taking into account special requirements, such as GOST, it is necessary to develop additional xsl for the formats of regular pages, title and final pages.
This may be the topic of the next article.
1.1. Output formats
With the choice of the final format, there are usually no problems, as the target operating system has its own requirements. For example, for programs for Windows, this is the format of CHM compiled help, for Linux and BSD systems, this is man. Common for all systems format for online help is html, and for printing - pdf.
The situation is complicated if it is necessary to have documentation in several formats - for distribution with the program (chm or man), for posting on the website (html) and for printing (pdf). It is possible that the content of the documentation in different formats may differ slightly. For example, it makes sense to include video clips in the online documentation, and in the print version they need to be replaced with a static image, possibly supplemented by qrcode links to the video fragment. In addition, the content of documents may vary for different categories of users, versions, delivery kits and other factors.
1.2. Source formats
Despite the seemingly obvious need for the use of specially created programs, this is not so simple.
')
Approaches differ depending on the target operating system.
1.2.1. Proprietary source formats
For example, to create compiled help for Windows in the chm format, Microsoft suggests using a special free HTML Help Workshop compiler. At the same time, source texts should be prepared in html format (editor is not included in the delivery), and table of contents files should be in a specific format. No means of forming printed manuals are provided.
Of course, specialized programs for creating help ( Robohelp , Help & Manual , HelpScribble and the like) provide a high level of service, have the ability to generate output documents in various formats and even to some extent profile the content.
However, they have the following disadvantages:
- First, all these systems are commercial and licensed by the number of jobs used.
- Secondly, the internal format they use is proprietary and is not supported by any software other than the one being sold. The ability to import files into a project will, of course, be provided to you, but you will not be able to export the project to any open format suitable for further processing. Even when used as an internal XML format (such as Help & Manual), its schema remains closed and not documented in any way.
- Thirdly, the ability to change the appearance of the output document is insufficient to form, for example, documentation in accordance with the requirements of GOST.
- Fourthly, it is extremely difficult to organize collective work with these programs, if possible.
1.2.2. Simple Markup Formats
A rational alternative is the use of simple and, as a result, quickly mastered markup formats.
Today there are several such formats:
- ASCIIdoc , used by de facto on Linux (BSD) systems;
- Wiki , used in various kinds of encyclopedias, and even gave them a common name;
- MarkDown is, so to speak, a “multi-purpose” documenting format.
All these markup use some symbolic non-tagged set of rules for the designation of the heading, illustrations and links, which implies editing in simple text editors. Preparation of a viewable view is carried out programmatically, usually on the server side.
For example, Wikipedia converts a Wiki format to HTML on the fly. The web portal of the Git system http://github.org is also capable of displaying documents in Markdown markup in a form suitable for reading in a browser.
1.3. Editors
Despite the fact that there are enough notepad features to create and edit source texts, some service functions, such as spell checking and markup highlighting, would be very useful for a writer.
The article http://www.ixbt.com/soft/markdown-online-2.shtml provides an overview of online editors with support for markdown syntax, and http://www.ixbt.com/soft/markdown-online-3 .shtml provides an overview of the five desktop editors that support the default markdown format, out of the box, so to speak.
One of these editors is MarkdownPad .
1.3.1. MarkdownPad
Figure 1. MarkdownPad 2 editor
As can be seen from the copy of the screen, the MarkdownPad 2 editor supports a live preview of the edited file with support for synchronous scrolling of the source text and the result of rendering.
When installing on Windows 8, a situation may arise when the preview is not available.
Figure 2. Report crash preview system
According to the developers of http://markdownpad.com/faq.html#livepreview-directx, this is due to the need to install the Awesomium 1.6.6 SDK , a specific web rendering SDK , which in turn uses DirectX .
The editor supports syntax highlighting, syntax checking of one language (including Russian), export to HTML, PDF formats (only in the paid version). In other words, MarkdownPad 2, like other special editors, is a good choice for a technical writer. In the same cases, when the user has to edit files of various formats, you can adapt your editor for editing texts with markdown markup.
1.3.2. Notepad ++
Notepad ++ can be considered an editor that adequately meets these requirements. Spell checking of many languages is supported using a special plug-in. And it supports text verification in several languages at the same time .
Figure 3. Notepad ++ editor
Despite the simplicity of the rules of markup, the author of the texts would be more convenient to work with syntax highlighting. With reference to Notepad ++, the project Markdown Syntax Highlighting for Notepad ++ will help, which, in essence, is the configuration file for the custom language Markdown. After installing it, the text in the editor looks like this.
Figure 4. Notepad ++ editor with markdown markdown elements highlighted
1.4. Quota
It is noteworthy that markdown editors even exist for mobile platforms. The figure shows a copy of the smartphone screen with the Quoda Code Editor running.
Figure 5. Quoda Code Editor - the universal editor for Android with markdown markup support
It should be said that most of this article is typed in this editor, and only then downloaded to the computer for revision.
Based on the analysis of the Markdown markup language and special editors, we can recommend their use for documenting systems of medium complexity.
1.4.1. Open Tag Formats
However, for the development of software documentation for large systems, an open, well-documented format should be used as the source format. As a means of formation, it is a tool with extensive capabilities for customizing the appearance, profiling and the ability to generate documents in various formats.
Systems such as DITA and Docbook fully meet these requirements.
Despite some differences, both systems have much in common:
- use as the source format documented (schematized) XML, which provides the ability to use for editing any XML editor with the validation function;
- for converting into one of the resulting formats, almost any xsl converter xslproc , xalan , saxon , etc .;
- to obtain a pdf document, an intermediate xsl-fo format is used, from which pdf is already formed by means of any fo processor (for example, Apache FOP or XEP );
- Numerous transformation parameters are used to customize the appearance and profiling, and, if necessary, by adding custom xsl templates.
It should be emphasized that these systems use semantic markup in the source documents. The appearance of the output is determined by the rules and parameters of transformations. This approach allows the author not to think about typography and design at the stage of writing source texts, but to focus solely on the semantic content.
At the same time, the practical experience of using, in particular, the Docbook, confirmed in a number of publications , showed that there are some difficulties with using such a well-thought technology:
- Creation of source texts in XML format of a specific scheme requires the technical writer to work with special editors;
- Good XML editors with Docbook support - commercial and expensive products (for example, oXygen XML Editor , Altova XMLSpy XML Editor );
- the rich features of XML markup entail a more complex format. For example, to insert an illustration with a signature in the Docbook markup, you need to use four nested tags.
Naturally, the above disadvantages constrain the widespread use of XML-oriented single source technologies.
If you use non-tagged formats for preparing offline or printed documentation, you need to use conversion utilities. Among many converters, the pandoc program deserves special attention.
1.5. Pandoc conversion utility
Pandoc is a cross-platform, command-line program that can convert texts in a wide variety of markup to multiple output formats.
For example, using pandoc, you can convert source documents in ASCIIdoc, Wiki, Markdown layouts to HTML. If you install LaTex, it becomes possible to receive and PDF.
For example, the conversion of the source text of this article into html format can be performed with the following command:
pandoc -f markdown pandoc.md -t html -o pandoc.html -H h.html
The result will be a ready html file:
Figure 6. HTML document formed from Markdown by the pandoc utility
For its versatility, the program is figuratively called the author of the "Swiss Army Knife."
Indeed, pandoc copes with converting without any loss of information. When converting from MarkDown format, it is possible to read three metadata parameters - title, author and date of the document. It also supports passing command line parameters to set some specific properties, such as the document language. It is possible to set your output template, modifying it to some extent.
For example, in the example above, it is assumed that in the current folder there is an h.html file that plays the role of the header. If we add a link to the style file in this file and, having defined
<base target="_blank"> , we get the following result:Figure 7. HTML document generated by pandoc using a header file with style links
As you can see from the example, the headings acquired their own style, and external links began to open in a new browser tab.
The above-described format capabilities make it justifiable to use Markdown markup to document relatively small software systems, for which no GOST requirements are required, which is proved by its wide use in the Git system.
As for large systems with extensive and complex documentation, for its creation seems to use the system of a single source Docbook. There may be transitional cases where the scale of the project does not appear immediately.
1.6. Docbook
The difficulty of creating source XML sources can be overcome by using Markdown sources and converting them to a Docbook. This conversion is supported by the pandoc utility. So the team
pandoc -f markdown pandoc.md -t docbook -o pandoc4.xml -H h.xml
will create the resulting file .
The use of the
h.xml header file (you can simply empty it) is necessary for the correct processing of meta tags and the formation of an article.Figure 8. The generated article in the XML editor
There are several additional markdown markup requirements that will be used to convert to a docbook:
First, you should avoid using angle brackets (<and>) in the text, since in XML they are used to extract tags, and the converter leaves them as is. If the angle brackets are needed by meaning, then you should use the entities
< and > .Secondly, when inserting a picture, it is necessary to enter alternative text, since pandoc uses it to create the required
title tag for the figure tag.However, the output text is formed in the obsolete Docbook 4 version format, while the modern 5 version provides significantly richer semantic markup features.
To convert text from version 4 to version 5, you can use the special conversion db4-upgrade.xsl included in the Docbook package.
xsltproc -o pandoc5.xml db4-upgrade.xsl pandoc4.xml
Thus obtained xml file docbook 5 schema can be used when forming a single source.
Figure 9. Schema article in XML editor in author mode
The described chain of transformations may seem at first glance long and unnecessarily complex. However, once you have mastered the necessary tools and developed command files (scripts) for frequently performed tasks, you can save a considerable amount of time in the future.
It should be emphasized that the technology of a single source has a pronounced cumulative effect. The initial time spent on the development of typical reusable text fragments is paid off when they are used in subsequent projects. It is this quality that makes the technology of a single source particularly attractive when documenting serial software systems.
A set of transformations Docbook supports the formation of documents in HTML with styles, PDF for printing so to say "out of the box."
xsltproc -o pandoc5.fo c: \ <Path to DocbookXSL> \ fo \ docbook.xsl pandoc5.xml
The appearance of the output can be configured to a certain extent using parameters. The resulting file format FO-XSL pandoc5.fo is intermediate and is needed to build the final PDF .
The possibility of automatically generating a table of contents, a list of illustrations, listings, tables, an index, a glossary of terms, and a list of references is also important.
With a large number of documents in the package, it is also possible to create a separate list with the possibility of automatically generating properly designed links to them. In the case of the preparation of a typographical layout of the manual taking into account special requirements, such as GOST, it is necessary to develop additional xsl for the formats of regular pages, title and final pages.
This may be the topic of the next article.
Source: https://habr.com/ru/post/250155/
All Articles