![]() The stylesheets will ensure that all our documentation has the same look-and-feel. Nah… better put the rules in one central place: the stylesheets, and let the docmakers worry about documentation, not presentation. Of course we could develop a set of makeup rules, but then every docwriter would have to be aware of those rules, and take care to apply them all the time. If they all used different formats, or even one single format like Word or HTML, their works would look very different because every contributor would make his or her own makeup decisions. Many people produce docs for the manual module. ![]() Word, but I promise you: you’ll soon get to love it.īecause DocBook is all about structure and meaning, it will be surprisingly easy to transform your outline into a DocBook skeleton. This practice may at first feel a little odd if you’re used to writing text in e.g. ![]() You can concentrate on structure and informational content. You never have to worry about the presentational side of things while writing your doc That’s why the rules are mostly defined in stylesheets.Ī stylesheet is a document that tells the tool stuff like:Ī DocBook XML document consists of pure, unpolluted, content. This decision (or rather: the rendering rules) can be hardcoded in the tools but that would make things very inflexible. In DocBook, you’ll find structural tags like, ,, ,, and semantic tags like, ,, but nothing like, ,, , – nothing that has to do with layout or makeup.īecause of this, a decision has to be taken somewhere on how the DocBook tags are translated into presentational makeup. If you use undefined tags, or if you don’t follow the rules, your document isn’t DocBook anymore (and DocBook-supporting processing tools may break on it).ĭocBook tags always convey structure and semantics (meaning), never makeup. The DocBook DTD defines a limited number of tags, and it gives exact rules on how to use them: what attributes are possible for a tag A, whether element B can be nested within element C, and so on. The posting frequency can be very low at times, but rest assured that if you post there, your message will be read, and replied to. Talk about your ideas – or your search for ideas – on the firebird-docs list. Or maybe you can supply raw documentation material for a subject you know a lot about. ![]() Maybe you can write one or more chapters for a book. Maybe there are already people working on a larger production, which you can contribute to. You don’t necessarily have to write an entire book, guide or article. The most logical choice would be a topic you are familiar with, but you can also pick a subject you’d have to learn more about first (this is much more work of course, but a great learning experience if you’re willing to invest the time). Then ask yourself what’s missing, and what may be useful for Firebird users in general, or perhaps just for a specific group.Īlso ask yourself what you would like to write about. Translator’s notices in DocBookįirst make sure you know what’s already there – nobody’s waiting for three MS-SQL-to-Firebird conversion guides. A copyright notice at the start in DocBook Program listings, screens, literal layout, and examples A copyright notice at the start in AsciiDoc ![]() Firebird documentation AsciiDoc code style AsciiDoc and Asciidoctor - an introduction Updating the Firebird Documentation Index Publishing your document on the Firebird website Dos and don’ts if you have received commit rights Adding your document to the firebird-documentation repository Attaching the entire Public Documentation License ![]()
0 Comments
Leave a Reply. |