DE19708751A1

DE19708751A1 - Reference manual and/or on-line manual automised manufacture

Info

Publication number: DE19708751A1
Application number: DE19708751A
Authority: DE
Original assignee: GFAI GES ZUR FOERDERUNG ANGEWA
Current assignee: GFAI GES ZUR FOERDERUNG ANGEWA
Priority date: 1997-02-25
Filing date: 1997-02-25
Publication date: 1998-08-27

Abstract

The automised manufacture uses digital control characters and/or control sequences for marking individual parts of the source text internal documentation of the programmes which are associated with the manual documentation parts. The marked documentation parts in source text are identified, separated out and temporarily stored on a storage medium, for further processing to provide a printed handbook.

Description

Die Erfindung betrifft ein Verfahren zur automatisierten Herstellung von Referenz-Manuals sowie nach dem Verfahren hergestellte Referenz-Manuals. Die Erfindung ist anwendbar insbesondere zur Herstellung von Handbüchern unterschiedlichen Umfangs in Papierform oder auf Datenträgern.The invention relates to a method for automated production of reference manuals as well Reference manuals produced according to the procedure. The invention is particularly applicable to Manufacture of manuals of various sizes in paper form or on data carriers.

Softwareentwicklungen sind eng verbunden mit Schreibarbeiten - es werden Programme geschrieben. Diese Programme gliedern sich in verschiedene softwaretechnische Einheiten wie Funktionen, Makros, Definitionen, Klassen und Memberfunktionen innerhalb der Klassen. Der Umfang der Programme wächst mit zunehmendem Entwicklungsaufwand stark an. Wenn ein Referenz-Manual gefordert ist, dann fällt ein entsprechend umfangreicher Schreibaufwand ein zweites Mal an. Denn ein Referenz-Manual bedeutet, daß alle einzelnen softwaretechnischen Einheiten wie Funktionen, Makros, Definitionen, Klassen und Memberfunktionen in den Klassen mit jeweils einer Beschreibung dokumentiert werden. Software developments are closely related to Paperwork - programs are written. These programs are divided into different ones software engineering units such as functions, macros, Definitions, classes and member functions within of classes. The scope of the programs grows with them increasing development effort strongly. When a Reference manual is required, then comes to mind correspondingly extensive writing effort a second At times. Because a reference manual means that all individual software engineering units such as functions, Macros, definitions, classes and member functions in each class is documented with a description will.

Ein Referenz-Manual ist immer dann nötig, wenn es nicht genügt, die Software als ein abgeschlossenes Endprodukt aus der Hand zu geben (in dem Fall würde eine Beschreibung für den Anwender, d. h. ein "User Manual", genügen), sondern wenn die Zielgruppe auf Basis der erzeugten Software eigene Entwicklungen tätigt und deshalb die interne Struktur und Funktionalität der Software mehr oder weniger im einzelnen kennen muß. Der letztgenannte Fall liegt vor allem bereits innerhalb einer Entwicklungsfirma vor. Wenn mehrere Personen oder mehrere Teams an einer Software arbeiten, dann muß organisiert werden, wie bestimmte Teilentwicklungen auf wiederum anderen Teilentwicklungen aufbauen. Hierbei wäre ein Referenz-Manual die ideale Grundlage, wenn es existieren würde, d. h. wenn sein Herstellungsaufwand verkraftbar wäre. Erst durch die Möglichkeit der automatischen Herstellung eines Referenz-Manuals wird es verkraftbar, mehrfach, zu einem beliebigen Zeitpunkt innerhalb eines Entwicklungsprojektes ein Referenz- Manual herzustellen, das den aktuellen Entwicklungsstand genau beschreibt.A reference manual is always necessary if it is not the software is sufficient as a finished end product to hand over (in which case one would Description for the user, d. H. a "User Manual", suffice), but if the target group is based on the software creates own developments and hence the internal structure and functionality of the Software needs to know more or less in detail. Of the the latter case is already within a development company. If several people or if several teams work on one software, then must be organized on how certain sub-developments build other sub-developments. Here a reference manual would be the ideal basis if it would exist, d. H. if its manufacturing expense would be tolerable. Only through the possibility of automatic production of a reference manual it manageable, multiple times, at any time a reference within a development project Manual that the current Describes the state of development precisely.

Ein Referenz-Manual kann in verschiedenen Formen vorliegen: in Form eines umfangreichen Buches, in Form einer Quickreferenz, welche die zu beschreibende Funktionalität nur überblicksmäßig beschreibt, und in Form eines online-Manuals. Bei letzterem schlägt man die einzelnen zu beschreibenden Einheiten am Display nach. Besonders günstig ist hierbei das HTML-Format, welches im World Wide Web bekannt ist. Dieses erlaubt, daß sich der Leser auf der Suche nach Informationen in der Gesamtheit der Beschreibungen leicht und effektiv entlang der bestehenden Querverweise, Gliederungspunkte und Einträge im Sachverzeichnis bewegen kann. A reference manual can take various forms available: in the form of an extensive book, in the form a quick reference that describes the Describes functionality only in an overview, and in Form of an online manual. With the latter one strikes the individual units to be written on the display after. The HTML format is particularly cheap, which is known on the World Wide Web. This allows that the reader is looking for information in the whole of the descriptions easily and effectively along the existing cross-references, outline points and can move entries in the subject index.

Der bekannte Stand der Technik ist gekennzeichnet durch eine zweifache Schreibarbeit: Zuerst die eigentliche Programmierung, das Schreiben der softwaretechnischen Bausteine und später das Schreiben der Dokumentation der realisierten softwaretechnischen Bausteine im Referenz-Manual.The known prior art is characterized by a double paperwork: first the real one Programming, writing the software engineering Building blocks and later writing the documentation of the implemented software engineering components in the Reference manual.

Diese Auftrennung in zwei verschiedene Formen der Schreibarbeit ist nachteilig. Sie erzeugt einen typischen Zielkonflikt: Wenn im Softwareprojekt die Zeit gekommen ist, ein Referenz-Manual zu schreiben, dann können zur gleichen Zeit auch fällige Verbesserungen an der Software realisiert werden, was aber dazu führen würde, daß das Manual nicht mehr aktuell ist. Dieser Zielkonflikt ist normalerweise unlösbar. Denn beide Wünsche - die Software zu verbessern, sie zu verändern, zu erweitern oder ähnliches, und ein gültiges Manual zu haben, machen sich gegenseitig zunichte. Die Folge ist, daß für Softwaresysteme ein sowohl umfangreiches wie auch aktuelles Manual nur sehr selten existiert.This split into two different forms of Paperwork is disadvantageous. It creates one Typical conflict of objectives: If the Time to write a reference manual then also due ones can be made at the same time Software improvements are realized what but would result in the manual no longer is current. This conflict of goals is normal unsolvable. Because both wishes - the software too improve, change, expand or do similar things and have a valid manual cancel each other out. The result is that for Software systems a both extensive as well current manual only very rarely exists.

Der genannte Zielkonflikt wird dadurch verschärft, daß das Referenz-Handbuch für eine umfangreiche Software schnell auf Buchdicke anwächst, und der Programmierer das ganze Buch halbjährlich neu editieren müßte, wenn er nur einige sinnvolle Verbesserungen realisierte.The conflict of objectives is exacerbated by the fact that the reference manual for extensive software quickly grows to book thickness, and the programmer would have to re-edit the entire book every six months if he just made some meaningful improvements.

Der Erfindung liegt daher die Aufgabe zugrunde, ein Verfahren zur automatisierten Herstellung von Referenz- Manuals zu schaffen, welches es gestattet, die Trennung zwischen den zwei verschiedenen Formen der Schreibarbeiten - erstens die Programmierung der softwaretechnischen Bausteine, zweitens deren Dokumentation mittels Textbausteinen im Referenz-Manual - weitgehend aufzugeben und welche es erlaubt, die laufende Programmierarbeit durch den Einsatz technischer Mittel so zu gestalten, daß zu einem beliebigen Zeitpunkt der Entwicklungsarbeit das momentan aktuelle Referenz-Manual automatisch auf Basis der klassischen quelltextinternen Dokumentation erstellt werden kann.The invention is therefore based on the object Process for the automated production of reference To create manuals that allow the separation between the two different forms of Typing - firstly programming the software engineering components, secondly their Documentation using text modules in the reference manual - largely give up and which allows the ongoing programming work through deployment to design technical means in such a way that any time of development work that currently current reference manual based automatically the classic documentation within the source text can be created.

Es ist weiterhin Aufgabe der Erfindung, ein derartiges Referenz-Manual zu schaffen.It is a further object of the invention to provide such Create reference manual.

Diese Aufgabe wird erfindungsgemäß gelöst durch die Merkmale im kennzeichnenden Teil der Ansprüche 1 und 6 in Verbindung mit den Merkmalen im jeweiligen Oberbegriff. Zweckmäßige Ausgestaltungen der Erfindung sind in den Unteransprüchen enthalten.This object is achieved by the Features in the characterizing part of claims 1 and 6 in conjunction with the features in each Generic term. Useful embodiments of the invention are contained in the subclaims.

Ein besonderer Vorteil der Erfindung besteht darin, daß Referenz-Manuals ohne bzw. mit nur geringer zu sätzlicher Schreibarbeit und verschiedenen Umfanges verschiedener Zusammensetzung und verschiedener Form automatisch hergestellt werden können, indem zumindest einzelne Bestandteile der klassischen quelltextinternen Dokumentation von Programmen mit in digitaler Form vorliegenden Steuerzeichen und/oder Steuersequenzen markiert werden, welche diese Dokumen tationsbestandteile dem Manual zuordnen, die markierten Dokumentationsbestandteile im Quelltext identifiziert, separiert, in einem Speichermedium zwischengespeichert und weiterverarbeitet werden derart, daß sie zu einem Referenz-Manual zusammengefügt, und drucktechnisch in einer handbuchüblichen Form ausgegeben oder online auf dem Bildschirm dargestellt werden.A particular advantage of the invention is that Reference manuals with little or no to additional paperwork and various volumes different composition and different shape can be made automatically by at least individual components of the classic source text Documentation of programs with in digital form existing control characters and / or control sequences be marked which these documents Assignment components to the manual, the highlighted Documentation components identified in the source text, separated, temporarily stored in a storage medium and processed in such a way that they become one Reference manual put together, and typographically in issued in a standard form or online displayed on the screen.

Die entstehende, zusätzliche Schreibarbeit für das Markieren der Text-Bausteine mit in digitaler Form vorliegenden Steuerzeichen ist völlig geringfügig. Es wird bereits dadurch mehr Schreibarbeit gespart, daß das automatische Verfahren die Namen und Deklarationen von Software-Bausteinen selbständig aus dem Quelltext entnehmen kann.The resulting additional paperwork for the Mark the text blocks with in digital form present control character is completely minor. It more paperwork is saved by the fact that the automatic procedure the names and declarations of software modules independently from the source text can see.

Ein weiterer Vorteil ist, daß die Korrektheit der quelltextinternen Beschreibung vom Extraktionsprogramm bis zu einem gewissen Grade geprüft werden kann, z. B. kann geprüft werden, ob alle geforderten Rubriken der Beschreibung ausgefüllt sind.Another advantage is that the correctness of the Description of the extraction program within the source text can be checked to a certain extent, e.g. B. can be checked whether all the required categories of the Description are filled out.

Zusätzlich können mehrfach und bereits während der Softwareentwicklung ständig Referenz-Manuals auf dem aktuellen Entwicklungsstand automatisch generiert werden, wodurch sich das Projektmanagement entscheidend unterstützen läßt. Dies kann bereits ein hinreichender Grund für die Nutzung des automatisierten Verfahrens sein, selbst wenn zuletzt der Endnutzer, etwa beim Verkauf eines in sich abgeschlossenen Softwareproduktes, kein Referenz-Manual benötigt, das die internen Software-Bausteine dokumentiert. Insofern kann das automatische Verfahren zur Herstellung eines (internen) Referenz-Manuals im Rahmen jeder Softwareentwicklung aus Gründen eines verbesserten Softwaremanagements genutzt werden.In addition, multiple times and already during the Software development constantly reference manuals on the current development status automatically generated become crucial, which makes project management critical can support. This can already be a sufficient one Reason for using the automated process be, even if the end user is the last one, for example at Selling a self-contained Software product, no reference manual needed the internal software components are documented. To that extent can use the automatic method of making a (internal) reference manuals for everyone Software development for the sake of an improved Software management can be used.

Die endgültige Form und Ästhetik des erzeugten Refe renz-Manuals kann durch das automatische Verfahren zu seiner Herstellung kaum negativ beeinflußt werden. Denn die üblichen Mittel der Textverarbeitung für eine Verbesserung der Form bleiben erhalten; sie gehen durch das automatische Verfahren nicht verloren. Hinzu kommt jedoch die Möglichkeit einer besseren Vereinheitlichung der Form. So wie sich Standards für die Form von Referenz-Manuals durchsetzen, lassen sich diese in das automatische Verfahren zur Manual-Herstellung übernehmen.The final shape and aesthetics of the refe created renz-Manuals can through the automatic procedure too its production can hardly be influenced negatively. Because the usual means of word processing for a Improvement in shape is retained; they go through the automatic procedure is not lost. Come in addition however, the possibility of better unification the form. Just like standards for the shape of Enforce reference manuals, these can be automatic procedures for manual production take over.

Das automatische Verfahren basiert auf der klassischen quelltextinternen Beschreibung oder Dokumentation. Diese bedeutet zunächst - genau so wie bisher - folgendes: Zum gleichen Zeitpunkt, wie ein softwaretechnischer Baustein geschrieben wird, wird direkt bei diesem Baustein seine Beschreibung, bei spielsweise in Form eines "Quelltext-Kommentares", angefügt. Die Möglichkeit der programminternen Be schreibung bietet jede Programmiersprache. Entsprechend wird bei einer Änderung des softwaretechnischen Bausteines auch die dort vorhandene Beschreibung geändert. Was über die klassische Methode der quelltextinternen Dokumentation hinausgeht, ist, daß die quelltextinterne Dokumentation in einer Form verfaßt wird, die eine automatische Ableitung des aktuellen Referenz-Manuals zu einem beliebigen Zeitpunkt möglich macht. Und zwar gilt dies für alle avisierten Grundformen des Referenz-Manuals: seine ausführliche Form als Handbuch, seine Kurzform als Quickreferenz und die online-Darstellung auf dem Computerdisplay mit Hilfe eines HTML-Browsers. Die Bestandteile des Referenz-Manuals sind separierte Teile der quelltextinternen Dokumentation und separierte Quelltextteile.The automatic procedure is based on the classic one Description or documentation within the source text. This means - just like before - the following: at the same time as a software module is written its description directly at this module, at for example in the form of a "source text comment", added. The possibility of program-internal loading writing offers every programming language. Corresponding will change when the software Building block also the description there changed. What about the classic method of Documentation that goes beyond the source text is that the source code-internal documentation in one form is written, the automatic derivation of the current reference manuals for any Makes the time possible. This applies to everyone Notified basic forms of the reference manual: its detailed form as a manual, its short form as Quick reference and the online display on the Computer display using an HTML browser. The Separate parts are part of the reference manual the source code-internal documentation and separated Source parts.

Die Erfindung soll nachstehend anhand von Ausführungsbeispielen näher erläutert werden.The invention is based on Embodiments are explained in more detail.

Es wird mit einem Beispiel veranschaulicht, wie das klassische Verfahren der quelltextinternen Dokumentation erweitert werden kann, um eine automatische Generierung des Referenz-Manuals zu realisieren. Das Beispiel stellt nur einen kleinen softwaretechnischen Baustein dar. Das Grundprinzip läßt sich auf beliebige und beliebig komplizierte softwaretechnische Bausteine übertragen. Das Beispiel zeigt eine sogenannte Memberfunktion mit dem Namen string_printf in der Programmiersprache C++. Dieser softwaretechnische Baustein ist eine Sub-Einheit, die zur übergeordneten Einheit gSTRING (einer sogenannten C++-Klasse) gehört. Daher lautet der zusammengesetzte Name gSTRING::string_printf.It is illustrated with an example of how that classic procedures of source code internal Documentation can be expanded to include a automatic generation of the reference manual realize. The example represents only a small one software module. The basic principle is on any and arbitrarily complicated transfer software engineering modules. The example shows a so-called member function with the name string_printf in the programming language C ++. This software module is a sub-unit that to the parent unit gSTRING (a so-called C ++ class) belongs. Hence the compound Name gSTRING :: string_printf.

Der folgende Text ist ein Auszug aus dem Quelltext, d. h. dem Programm-Text. Zuerst kommt der Dokumenationstext, welcher innerhalb der Klammern /*. . .*/ geschrieben wird, danach folgt der eigentliche Programm-Text (Quelltext) der Funktion gSTRING:: string_printf.
The following text is an extract from the source text, ie the program text. First comes the documentation text, which is inside the brackets / *. . . * / is written, then the actual program text (source text) follows the function gSTRING :: string_printf.

Innerhalb der quelltextinternen Dokumentation befinden sich drei zusätzliche Steuersequenzen (@mef, @hdl, @d). Diese genügen als Anweisung für die Umwandlung des Software-Bausteines in den folgenden Text-Bausteinen im Referenz-Manual.
There are three additional control sequences (@mef, @hdl, @d) within the source code-internal documentation. These are sufficient as instructions for converting the software module in the following text modules in the reference manual.

Die automatische Erzeugung dieses Text-Bausteines basiert auf den drei Steuersequenzen @mef, @hdl, @d wie folgt. Die erste Steuersequenz besagt, daß im Programm- Text eine sogenannte Memberfunktion folgt (dies ist der Typ des Software-Bausteines). Daraufhin können einige Angaben des Text-Bausteines automatisch aus dem Programm-Text übernommen und in einem Speichermedium zwischengespeichert werden. Und zwar sind dies: der Name des Softwarebausteines (mus-sprintf), der Name des übergeordneten Software-Bausteines (gSTRING) und die für Referenz-Manuals notwendige Rubrik "Syntax", welche den programminternen Deklarationstext des Software- Bausteines enthält.The automatic generation of this text module is based on the three control sequences @mef, @hdl, @d wie follows. The first control sequence says that in the program Text is followed by a so-called member function (this is the Type of software module). Then some Information of the text module automatically from the Program text taken over and in a storage medium be cached. These are: the Name of the software module (mus-sprintf), the name of the higher-level software module (gSTRING) and the heading "Syntax" necessary for reference manuals, which the program-internal declaration text of the software Contains building block.

Über die genannten Angaben hinausgehend enthält der Text-Baustein im Referenz-Manual noch zwei weitere Rubriken, erstens die Titelzeile - hierher wird der Text übertragen, der sich nach der Steuersequenz @hdl (headline) befindet - und zweitens die eigentliche Rubrik "Beschreibung" - hierher wird der Text übertragen, der sich nach der Steuersequenz @d (description) befindet.In addition to the information given, the Text module in the reference manual two more Rubrics, firstly the title line - this is where the Transfer text that follows the control sequence @hdl (headline) - and secondly the actual one Rubric "Description" - this is where the text comes from transmitted, which follows the control sequence @d (description).

Das damit vorgestellte Prinzip-Beispiel zeigt, daß kaum zusätzliche Schreibarbeit nötig ist, um ausgehend von der quelltextinternen Beschreibung eines Software- Bausteines die dazugehörige Beschreibung im Referenz- Manual automatisch abzuleiten. Dem Mehraufwand für die Anordnung der Steuerzeichen @mef, @hdl, @d, welche sich bei Bedarf auch automatisch erzeugen lassen, steht gegenüber, daß die Rubrik "Syntax" sowie die Namen des Software-Bausteines eigens für das Referenz-Manual überhaupt nicht mehr notiert werden müssen, sie ergeben sich bereits automatisch aus dem Programm-Text. The principle example presented here shows that hardly additional paperwork is needed to start from the source-internal description of a software The corresponding description in the reference Manual derive automatically. The additional effort for the Arrangement of the control characters @mef, @hdl, @d, which are can also be generated automatically if required opposite that the heading "Syntax" as well as the names of the Software modules especially for the reference manual no longer need to be noted at all, they result already automatically from the program text.

Das Verfahren der automatischen Manual-Erzeugung basiert auf den folgenden dargestellten Wirkprinzipien. Ein Referenz-Manual umfaßt eine Sammlung von Text- Bausteinen eines verschiedenen Typs; jeder Text- Baustein enthält dabei mehrere Unter-Bausteine ("Rubriken"). Zum Beispiel gibt es einen typischen Text-Baustein zur Beschreibung des Software-Bausteines "Funktion" bzw. "Memberfunktion". Dieser enthält typischerweise die Rubriken Name Der Funktion, Titelzeile, Syntax-Rubrik, Beschreibung, Return-Rubrik, Kommentar. Statt der Rubrik "Kommentar" existiert in Referenz-Handbüchern häufig auch die Rubrik "Querverweise", "Siehe auch" oder "Beispiel". Diese Rubriken können in der quelltextinternen Beschreibung durch eine eindeutig identifizierbare (und meist stark abkürzbare) Steuersequenz deklariert werden. Zum Beispiel können in der Beschreibung des Software- Bausteines "Funktion" folgende Steuersequenzen die dazugehörigen handbuchüblichen Rubriken deklarieren: @headline (@hdl), @syntax, @description (@d), @return, @comment.The process of automatic manual generation is based on the following principles of action. A reference manual includes a collection of text Building blocks of different types; any text The module contains several sub-modules ("Rubrics"). For example, there is a typical one Text module for describing the software module "Function" or "Member function". This contains typically the categories Name of the function, Title line, syntax heading, description, return heading, Comment. Instead of the "Comment" section, there exists in Reference manuals often include the rubric "Cross-references", "See also" or "Example". This Rubrics can be found in the description within the source text through a clearly identifiable (and mostly strong abbreviable) control sequence can be declared. To the Example can be found in the description of the software Building block "function" the following control sequences Declare the corresponding standard rubric: @headline (@hdl), @syntax, @description (@d), @return, @comment.

Ebenso wird nicht nur der Name der Unter-Rubrik, sondern auch die Art des gesamten Text-Bausteines durch eine Steuersequenz deklariert. So kann die Steuersequenz @function (@fun) benutzt werden für den Software- und Text-Baustein "Funktion", die Steuersequenz @mefunction (@mef) für den Software- und Text-Baustein "Memberfunktion", die Steuersequenz @class für den Software- und Text-Baustein "C++-Klasse" usw.Likewise, not only the name of the sub-heading, but also the type of the entire text module declared a control sequence. So it can Control sequence @function (@fun) can be used for the Software and text module "function" that Control sequence @mefunction (@mef) for the software and Text module "member function", the control sequence @class for the software and text module "C ++ class" etc.

Das grundlegende Verfahrensprinzip ist, daß alle Text- Bausteine einer niederen oder höheren Gliederungsebene, die später im Referenz-Manual erscheinen sollen, bereits im Quelltext mit Hilfe einer kurzen Steuersequenz markiert werden. Damit wird es möglich, die Beschreibung aller softwaretechnischen Bausteine automatisch aus dem Quelltext herauszuholen und in ein Referenz-Manual zu überführen. Da die quelltextinterne Beschreibung unmittelbar am Ort erfolgt, können bestimmte Bestandteile der Beschreibung sogar automatisch generiert, d. h. aus dem Software-Baustein extrahiert werden.The basic principle of the procedure is that all text Building blocks of a lower or higher level of structure, that should appear later in the reference manual, already in the source text with the help of a short Control sequence are marked. This makes it possible the description of all software engineering components automatically get out of the source text and into one To transfer reference manual. Because the source code Description can be made directly on site certain parts of the description even automatically generated, d. H. from the software module be extracted.

Basierend auf diesem Verfahrensprinzip der Markierung der Text-Bausteine im Quelltext ist es möglich, eine spezielle Software zu entwickeln, mit deren Hilfe ein Referenz-Manual automatisch generiert wird. Sinnvoll ist es dabei, in zwei Schritten vorzugehen. In einem ersten Schritt wird die Software analysiert und die in ihr enthaltenen Text-Bausteine werden extrahiert. Der so erhaltene Beschreibungstext - hierzu gehören auch die Markierung der Text-Bausteine mit Steuersequenzen - muß anschließend weiterverarbeitet werden, um ihn mit modernen Methoden der Textverarbeitung in eine handbuchübliche Form zu bringen. Eine zweite Möglichkeit der Verarbeitung besteht darin, den Beschreibungstext umzuformen in einen Text im HTML- Format, welcher als online-Referenz-Manual genutzt werden kann.Based on this principle of marking of the text modules in the source text it is possible to use a to develop special software with the help of Reference manual is generated automatically. It makes sense is going to proceed in two steps. In one first step, the software is analyzed and the in The text modules it contains are extracted. Of the Description text received in this way - this also includes the marking of the text modules with control sequences - must then be further processed in order to use it modern word processing methods into one to bring handbook form. A second Possibility of processing is the Convert descriptive text into text in HTML Format used as an online reference manual can be.

Sofern eine Quickreferenz hergestellt werden soll, muß dann das Programm zur Extraktion des Beschreibungstextes nur bestimmte Teile der Beschreibung extrahieren, um diese danach in die Form einer Quickreferenz umwandeln zu können. In jedem Falle läßt sich das beschriebene Grundprinzip nach Belieben verfeinern, z. B. um bei der Herstellung von Referenz- Manuals bei Bedarf nur bestimmte Teile der Beschreibung zu extrahieren oder um bei Bedarf eine bestimmte Sortierung der Text-Bausteine vorzunehmen, d. h. Regeln festzulegen für die Reihenfolge, in der sie im Referenz-Manual erscheinen sollen.If a quick reference is to be established, then the extraction program Descriptive text only certain parts of the Extract description to get it into shape afterwards to convert a quick reference. In any case the basic principle described can be used at will refine e.g. B. in the manufacture of reference Manuals, if necessary, only certain parts of the description extract or order a specific one if needed To sort the text modules, d. H. regulate to be determined for the order in which they are in Reference manual should appear.

Bei der Manual-Herstellung ist die gezielte Extraktion von Subsets wichtig. Zum Beispiel darf eine praktische Kurzeinführung (z. B. ein Kapitel "Getting Started") nie die Ausführlichkeit haben wie ein komplettes Manual für den Programmierer, der auch die letzte programminterne Funktion beherrschen muß. Am häufigsten benötigen Programmierer in der täglichen Arbeit jedoch Quickreferenzen. Aufbauend auf obigen Prinzipien läßt sich eine Regie bei der Manual-Herstellung definieren, die insgesamt viele Optionen erlaubt. Die Regie definiert die Auswahl und die Reihenfolge der Text- Bausteine, die in das Referenz-Handbuch übergehen sollen. Sie kann z. B. mit Hilfe einer kurzen Textdatei fixiert werden, in welcher die Programme zur automatischen Manual-Erzeugung lesen. Die Regieanweisungen sind dann das Programm, welches die Herstellung des Referenz-Handbuches steuert.With manual production is the targeted extraction of subsets important. For example, a practical Short introduction (e.g. a chapter "Getting Started") never have the level of detail like a complete manual for the programmer who is also the last internal program Function must master. Most often need Programmers in daily work, however Quick references. Building on the above principles define a director of manual production, which allows many options. The director defines the selection and the order of the text Blocks that go into the reference manual should. You can e.g. B. with the help of a short text file are fixed in which the programs for read automatic manual generation. The Direction instructions are then the program that the Production of the reference manual controls.

Die Erfindung ist nicht beschränkt auf die hier dargestellten Ausführungsbeispiele. Vielmehr ist es möglich, durch Kombination der genannten Mittel und Merkmale weitere Ausführungsvarianten zu realisieren, ohne den Rahmen der Erfindung zu verlassen.The invention is not limited to that here illustrated embodiments. Rather it is possible by combining the means mentioned and Features to realize further design variants without leaving the scope of the invention.

Claims

1. Process for the automated production of reference manuals and / or online manuals, which serve to document software engineering modules and units, characterized in that

at least individual components of the classic source code-internal documentation of programs are marked with control characters and / or control sequences in digital form which assign these documentation components to the manual,
- The marked documentation components in the source text are identified, separated, temporarily stored in a storage medium and further processed in such a way,
- That they are put together into a reference manual and typographically given in a manual format or displayed online on the screen.

2. The method according to claim 1, characterized in that the compilation of the content of the reference Manuals can be controlled by the user, whereby he the ones to be included in the manual software engineering units, their order in Manual and possibly a short description of the individual software engineering units in the form a quick reference according to his needs specifies.

3. The method according to claim 1, characterized in that the further processed documentation components for display on the screen in a text in the HTML format to be transformed.

4. The method according to claim 1, characterized in that certain parts of the documentation text the software modules extracted and automatically inserted into the manual.

5. The method according to claim 1, characterized, that control sequences within the source code as Serve to parts of the source code as a command Copy the source code into the manual.

6. Reference manual for documentation and / or Description of software engineering components and Units, characterized in that the essential components sepa parts of the internal documentation are.