A Gentle Guide to Docbook brief introduction Docbook
How to use the portable document Creator How to use this portable document creation program
Author: Joe "Zonker" Brockmeier (jbrockmeier@earthlink.net) freelance writer Release Date: 1 September 2000 Translator: taowen (taowen.bitapf.org) translation Date: February 4, 2004 Source: IBM DeveloperWorks
Contents: What is DocBook Why use DocBook Creating a document with DocBook Including images Including code Including lists A basic template Converting to other file formats Exporting to HTML Exporting to plain text Exporting to PostScript Where to go next Resources About the author??
Directory: What is DocBook? Why use docbook? Creating a document with DOCBook Contains an image Containing code contains a list of simple templates to convert to other file formats Export to HTML Export to Pure Text Export to PostScript Next What Resources About Authors
This article explains what DocBook is and how to create a simple document using DocBook. Joe Brockmeier walks you through creating a document and using SGML-tools Lite to parse the document and make HTML, PostScript, plain-text, and PDF versions of the document . HE Also include, ignal references on docbook and tips lite and other docbook tools. This article explains what is docbook and create a simple document using Docbook. Joe BROCKMEIER takes you a document and uses SGML-Tools Lite to resolve the document creation document HTML, PostScript, plain text, and PDF versions. He also includes more reference materials for Docbook and how to find SGML-Tools Lite and other Docbook tools.
If you've ever thought about writing documentation for an open source project, or if you've browsed the Linux Documentation Project or any page dedicated to documentation for Linux or other open source projects, you've probably heard of DocBook. But you may NOT BE QUITE SURE What IT IS. If you have heard how to write documents to open source projects, or you have already browsed the Linux documentation item or any page of the document that serves Linux or other open projects, you may have heard of Docbook. But you may not be confident that it is.
What is docbook? What is docbook? DocBook is a markup language defined by an SGML or XML document type definition (DTD). Basically, DocBook is a set of tags that describe a document's structure. DocBook tags are similar to HTML tags, so if you've done any HTML, then DocBook will not be entirely foreign to you. DocBook is a bit more involved than HTML, but it is also much more useful than plain HTML because it facilitates the rendering of multiple formats from a single document. This article will describe how to create a SIMPLE ARTICLE (Document) in docbook and how to render severage document. docbook is a tag language defined by the SGML or XML Document Type Definition (DTD). Simply put, DocBook is a set of description documents labels. Docbook tags are similar to the HTML tag, so if you write HTML, then Docbook will not be too strange to you. Docbook is more complicated than HTML, but it is also much more useful than ordinary HTML because it provides a single document to a variety of formats. This article describes how to create a simple article (document) with Docbook and how to use SGML-Tools Lite to render several file formats from this document.
DocBook has been around, in one form or another, since 1991. Originally DocBook was created to help exchange UNIX documentation. Since then DocBook gone through four major versions and now is under the guidance of the Organization for the Advancement of Structured Information Standards, better KNOWN As Oasis (see resources). Docbook has been in various forms for a long time, starting from 1991. At first, Docbook was created to help swap UNIX documents. Since then, Docbook has experienced four major versions, and now is the formatting information standard progress organization, and more common is Oasis (see Resources), under the leadership.
Occasionally, the term DocBook is also used as a catchall term to describe the markup language and the tools used to convert DocBook documents into other formats. Technically, DocBook is only the DTD, but without SGML-tools Lite and other conversion tools DocBook isn ' T QUITE As Useful. Incidentally, the word Docbook is also used as a word for one million gold oil to describe the tag language and to convert the DocBook document to other formats. Technically, DocBook is just DTD, but there is no SGML-Tools Lite and other conversion tools, Docbook will not be too useful. Why use docbook? Why use docbook?
The main selling point for DocBook is its portability. A document written in DocBook markup can be converted into HTML, PostScript, PDF, RTF, DVI, and plain ASCII text easily and quickly without any expensive tools. In fact, DocBook and all of the tools used to work with DocBook are freely available under open source licenses. DocBook documents are plain text, and can be edited with any text editor or word processor that can save documents as plain ASCII text. Note that if you use a word processor, take extra care to save DocBook documents as plain text;. otherwise they will not parse correctly If you'll want to use your documentation in more than one format, like print and online, you'll find DocBook is a great solution DocBook major. The selling point is portability. A document written in a Docbook markup can quickly and easily convert to HTML, PostScript, PDF, RTF, DVI, and ASCII plain text, and do not require any expensive tools. In fact, Docbook and all the tools used by all supporting DocBook are freely used in open source authorization. The DocBook document is plain text and can be edited by any text editor or a word processor capable of storeing a document as an ASCII text. Note that if you are using the word processor, you should pay attention to put the docbook as plain text; otherwise they can't be parsed correctly. If you don't want to use your documents in a format, like printing version and web version, you may find that docbook is an excellent choice.
Another advantage of DocBook is that it frees the author from worrying about the formatting and layout of a document. DocBook is only concerned with the structure of a document. For instance, an author simply uses the DocBook markup to indicate text that should be emphasized with the tag. Depending on what format the document is converted to, the emphasized portion may be italicized, underlined, or set in boldface type. This is one less thing for the author to worry about while writing a document. DocBook further One advantage is that it will free from the scope and format of the documentation. Docbook is just concerned with the structure of the document. For example, an author simply uses the DocBook tag to indicate that text needs to be emphasized. Depending on why formats need to be converted, it is emphasized to become a bevel, underscore, or set to bold. This is no longer the author worried when writing documents. Creating a document with docbook Create a document with DOCBOOK
Creating a document with DocBook is easy. We'll focus on creating a document using the SGML DTD. With the exception of the document declaration, everything in this article should apply to XML as well as the SGML DTD. Is not difficult to create a document with DocBook . We will concentrate on how to create a document using SGML DTD. In addition to documentation declaration, all content in this article can be used for XML and SGML DTDs.
To begin, Fire Up your favorite. The first line of a docbook document is the document declaration. First, open your favorite text editor and create a new document. The first line of the Docbook document is the document statement.
Every DocBook document requires a document declaration to be considered valid. This lets SGML-tools Lite, or whatever tool you're using, know what version of the DTD you are using and the type of document that you are creating. All DocBook to become Valid requires a document statement. This makes SGML-Tools Lite or any other tool you are using, know the version of the DTD and the type of document you created.
Now we'll start adding a little meat to the document. We'll start with a title, author information, and a short paragraph. This brief example shows a few of the basic DocBook tags, or elements, in use. While DocBook elements may look similar to HTML tags, remember that DocBook parsers are much more demanding than your average Web browser. While you can get away with not declaring an HTML document, or even skipping some "required" tags, DocBook is not quite so forgiving. Be Careful to include All Required Elements and use the their proper order. Now we start to add some content to the document. From the title, author information and a small paragraph. This short example shows some labels for the basic DocBook, or elements. Docbook's elements may look similar to the HTML tag, but remember that docbook parsers are strict than your web browser. You may not declare the HTML document, even omitted some "must" tags, but DocBook will not be so wide. Note that all necessary elements and use them in a suitable order. a business guide to docbook </ title> <author> <firstname> Joe </ firstname > <Surname> BROCKMEIER </ Surname> </ author> </ articleinfo> <subject1 label = "1.0"> <title> a brief introduction to docbook </ title> <para> if You've Ever Thought About Writing Documentation for An Open Source Project ... </ para> </ subject1> </ article></p>
<p>Most of the elements used here are self-explanatory. Some of the elements, such as the <firstname> and <surname> elements, are only valid when nested inside their parent elements. The <firstname> and <surname> elements, for example Are Valid Nested Within Their Parent Element <Author> But Would NOT BE VALID IF Used WITHIN THE <PARA> Element. The most elements used here are meaningful. Some elements, such as <firstname> and <Surname> elements, only in their parent elements. For example, <firstname> and <Surname> Elements are nested in their parent elements <author> but if they are used in <para> elements. There Are Five Levels of The SECT Element: <SECT1> THROUGH <SECT5>. Unlike html where you can skip from a <h1> tag to a <h3> tag, you cannot Skip from a <subject1> to a <subject3> Element . Docbook is much strict Than HTML. SECT element has 5 levels: <SECT1> to <SECT5>. Unlike html, you can ignore the <h1> tag directly to the <H3> tag, you can't cross <SECT1> to the <SECT3> element. Docbook is strict than HTML.</p>
<p>The next element is the <para> element. The <para> element is easy to remember because it stands for paragraph. You will probably find that the majority of DocBook elements make sense, and you probably will not need to look up the common Elements After Writing One or Two Documents with docbook. The next element is <para>. <para> element is easy to remember because it is paragraph (paragraph). You may find that most elements of docbook are meaningful, and you may have written a two document with Docbook, you don't need to find a common element.</p>
<p>Some elements in DocBook can also include attributes that further describe the element. The <sect1> element in the above example includes a label attribute. Generally elements have optional attributes. However, some elements like the <ulink> element require an attribute. If you 'RE Unsure, Check The Official Docbook Documentation TO See What attributes Are Applicable To The Elements You Are Using (See Resources). Some elements in the DocBook can also include the properties of the further description of the elements. The <SECT1> element of the previous example contains a Label property. Usually the elements have optional properties. However, some element images must have attributes <Ulink>. If you don't believe, check the official DocBook documentation which properties can work for the elements you are using. (See Resources) Including Images contains images</p>
<p>To include an image in your document, you can use any of several elements. The <graphic> element is being phased out in favor of the <imageobject> element, so we will focus on the use of the <imageobject> element. Should Images are included in your document, you can use several elements. <graphic> element is worse than <imageObject> elements, so we will pay attention to the use of <imageObject> elements.</p>
<p>To include an image in your document, you will use three elements: the <imageObject> element, and the <imagedata> element. To include images in your document, you will use three elements: < MediaObject> Elements, <imageObject> elements, and <imagedata> elements.</p>
<p><MediaObject> <imageObject> <imageData fileref = "images.d / fuzzy.eps" format = "EPS"> </ imageObject> </ mediaobject></p>
<p>This code includes the fuzzy.eps image in your document when you render it using SGML-tools Lite or one of the other DocBook conversion tools. Note that eps is a good format for printing documents or converting to PDF, but you would want to use A JPEG, GIF, OR PNG File for Web Publication. The Docbook Rendering Tools Do Not Convert Image File Formats, So You'll NEED To Have Type Output You Want To Use. When you use SGML- Tools Lite or other Docbook Conversion Tool When you render it, these codes contain Fuzzy.eps images in your document. Note that the EPS is used for a good format that is converted to PDF due to documents or converted to PDF, but you may use JPEG, GIF, or PNG files to be published in the network. The DocBook rendering tool does not convert file format, so you need to keep them native formats for any type of output you want. INCLUDING CODE contains code</p>
<p>Often when writing documentation it is useful to quote source code within the document. The <programlisting> element is used to display source code as is. This is similar to the <pre> tag in HTML, however the <programlisting> element can include other Docbook Elements That Will Get Interpreted. When writing a document, it is useful to reference the source code in the document. <programlistic> element is used to display source code. This is similar to the <pre> tag in HTML, however <ProgramListing> elements can contain other DocBook elements that will be interpreted.</p>
<p><para> <programlistic () {global $ db, $ g_URL; $ sql = "select *, date_format (birthstamp, '% c /% E /% Y @% h:% i% p')" $ SQL. = "as date from t_pollquestions"; $ Question = @Mysql_Query ($ SQL, $ dB); $ nquestion = mysql_num_rows ($ Quest); F_Start ("List of polls"); if ($ nquestion> 0) { } else {print "There no polls available at this time.";} f_end ();} </ programlisting> </ para></p>
<p>Note that the above code uses the <and> characters, which would cause problems in an HTML document. SGML-tools Lite converts <and> to their appropriate escape codes when converting to HTML. Note that the above code uses the <and> characters, This will result in problems in the HTML document. SGML-Tools Lite converts <and> convert <and> convert <and> to its corresponding escape character when converting to HTML. INCLUDING LISTS contains lists</p>
<p>One Thing That You'll Probably Want To Do As Well Is Make Lists - Either Bulleted Lists or Numbered Lists - Using The <ItemizedList> Element: You may not be like doing a list - point list or serial number List - use <itemizedlist> elements:</p>
<p><Para> this is how you create an non-numbered list. </ para> <itemizedlist> <ListItem> <Para> this is a list entry </ para> </ listitem> <listitem> <para> this is another List Entry </ para> </ listitem> </ itemizedlist> <para> this is how you create a numbered list. </ para> <orderdlist> <listitem> <para> this is a list entry </ para> </ listitem > <ListItem> <Para> this is another list entry </ para> </ listitem> </ orderdlist></p>
<p>The <ListItem> Can Be Used with Either The <OrderedList> or the <itemizedlist> Elements. It cannot be used by itself, however. <ListItem> can be used in <OrderedList> or <itemizedList> elements. However, it cannot be used alone.</p>
<p>A Basic Template A simple template</p>
<p>When I started learning DocBook I found it was easier to create a basic template rather than trying to remember all of the necessary elements off the top of my head. This is a basic article template, which may help you get started on your first DocBook documents . you should be able to simply cut and paste this from your browser into your favorite text editor and get started. you should check to be sure that the version of DocBook you are using is the same as the version in the declaration in the template. IF not, be sure to change it to the property. I found a simple template when I started learning Docbook, I am quite easy to try to remember all necessary elements in my brain. It is not so easy. This is a basic article template that will help you start writing your first Docbook document. You should be able to simply cut and paste it from you to your most common text editor and start. You should check that you want to use the version number of docbook, is the same as the version declared in the template. If not, make sure you change it to the right version. <! Doctype article public "- // ias // DTD Docbook v4.1 // en"> <article> <articleinfo> <title> sample docbook template </ title> <author> <firstname> firstname here </ firstname> <Surname> Lastname Here </ Surname> </ author> </ articleinfo> <subject1> <title> section 1 title </ title> <para> this is a paragraphone </ para> <subject2> <title> section 2 Title </ title> <para> this is another paragraph ... </ para> </ sect2> <sect2> <title> section 2 Pt. 2 </ title> <para> yet another paragraph ... </ para > </ Sect2> </ subject1> </ article></p>
<p>Converting to Other File Formats Convert to Other Files</p>
<p>Often authors will use DocBook and never actually need to render the documents into other formats themselves. However, if you need to once you have a finished DocBook file, you can then convert that file into several other types of files using SGML-tools Lite. If you're using a Linux distribution, you may already have SGML-tools Lite or SGML-tools already installed. you may want to check and see if they're already installed and working, or if they are on your installation CDs. writing People often use docbook but never use themselves to render documents to other formats. However, if you need, as long as you have a completed docbook file, you can convert the file to several file formats with SGML-Tools Lite. If you are using Linux, you may have installed SGML-Tools Lite or SGML-Tools. You may want to check if you have already installed it, or they are on your installation CD. If you get errors when trying to parse your DocBook files, check the syntax of your document. Often something as simple as a forgotten "/" or misplaced element is the only problem. Get an error if you try to resolve your DocBoo file Check the syntax of your document. Regular problems are just simple or misunderstanded elements like forgetting "/".</p>
<p>If you do not have them already installed, and you want to be able to render documents yourself, you can download them from the SGML-tools Lite home page. To get the latest version, go to the SGML-tools Lite home page hosted On SourceForge (See Resources) and Download Either the Source OR RPM AND FOLLOW The Instructions on The SGML-Tools Lite Home Page To Install Them. If you haven't installed them, you want you to render documents, you can from SGML -Tools Lite's home page downloads them. To get the latest version, go to the homepage of SGML-Tools Lite (see Resources) (see Resources) and download the either source code or RPM, follow the instructions on the SGML-Tools Lite home page to install them.</p>
<p>Exporting to HTML exported to HTML</p>
<p>To Export a docbook document named filename.sgml to html, Simply Type The FOLLOWING: To export the name for FileName.sgml to HTML, simply use:</p>
<p>sgmltools -b html filename.sgmlIf the document has no major errors, SGML-tools Lite will produce a "filename" directory with the resulting HTML files inside. If the document is no major errors, SGML-tools Lite will produce results within a HTML The "filename" directory of the file.</p>
<p>Exporting to Plain Text Export to Pure Text</p>
<p>Docbook Also Supports Plain-Text Documents. To Render A Plain Ascii-text Document, Use The Following Command: Docbook also supports plain text documentation. To render a pure ASCII text document, use the command:</p>
<p>SGMLTOOLS -B TXT FileName.sgml</p>
<p>This Is The Same As the Command Used to Convert To HTML, Except We've Replace "HTML" with "txt". The -b argument txt "as the" backend ". Currently there several backends That Are Available: HTML, TXT, RTF, PS, AND DVI. This is the same as commands used to convert to HTML, except that we replace "HTML" to "TXT". The -b parameter tells SGML-Tools to use "TXT" as "backend". There are several Backend available: HTML, TXT, RTF, PS, and DVI.</p>
<p>Exporting to PostScript Export to PostScript</p>
<p>. DocBook is capable of producing output suitable for commercial printing through PostScript When converting to PostScript the command syntax is the same as for text or HTML: DocBook able for commercial printing through PostScript. Convert the syntax of the command of PostScript and the same as the text and HTML:</p>
<p>SGMLTOOLS -B PS filename.sgml</p>
<p>However, it is worth noting that if you are including images in the document, you will need to have them saved in EPS format to have them included in the PostScript document. SGML-tools Lite will not covert GIF or JPEG to PostScript for inclusion in However, if you contain this worthless of the image in the document, you will need to save them as the EPS format to enable them in the PostScript document. SGML-Tools Lite does not convert GIF or JPEG to PostScript for inclusion in the final document.</p>
<p>What is the next step in Where to Go Next?</p>
<p>This has just been a brief overview of using DocBook. It is by no means an exhaustive look at all of the elements or potential that DocBook has. Hopefully, however, this article will suffice to get you started learning more about DocBook. After following along with this article you should be able to create basic DocBook documents and use SGML-tools Lite to produce usable output from DocBook files. for more information on DocBook, you can consult the online documentation at DocBook.org (see Resources). this is for Use the short overview of Docbook. It does not have observations for the potential of elements and docbook. However, I hope this article is enough to start more learning for DocBook. After reading this article, you should be able to create a basic DocBook document and use SGML-Tools Lite to create a useful output from the DocBook file. To get more information about DocBook, you can query online documents located in docbook.org. (See Resources) If you would like to tinker a bit more with DocBook, a good place to start might be the Linux Documentation Project. Most of the documents in the LDP have a DocBook version available online that you could examine for more detailed usage of Docbook. If you want to have more observations for DocBook, a good place is Linux documentation project. Most documents in LDP have Docbook versions, you can learn more detailed use of DocBook.</p>
<p>Resources resources</p>
<p>Visit Docbook.org, The Main Docbook Site. Access Docbook.org, the primary site of Docbook.</p>
<p>The Linux Documentation Project Contains Many Documents Written in docbook. The LDP Authes The Started The Docbook.linux documentation contains many documents written in docbook. LDP authors have some tips on how to DocBook doors.</p>
<p>Download either the source or RPMs at SGML-tools Lite and follow the instructions to install them. This site has the tools you need to convert DocBook documents to HTML, PDF, PostScript, RTF, or plain text. Download SGML-tools Lite Source Code or RPM. This site has the tool you need to convert the DocBook document to HTML, PDF, PostScript, RTF, or plain text.</p>
<p>At The Oasis Docbook Pages, You'll Find The Docbook Technical Committee Home Page. You will find the homepage of the Docbook Technical Committee. For help getting started with any sgml dtd, see the w3c overview of sgml resources. To help SGML DTD, see W3C overview of SGML resources</p>
<p>For more details, see the general sgml / xml Applications, Oasis' Guide to SGML / XML Apps. To get more details, see General SGML / XML Applications, Oasis SGML / XML program guidance.</p>
<p>About the Author about the author</p>
<p>Joe "Zonker" Brockmeier is a contributing editor for Linux Magazine and has written Install, Configure and Customize Slackware Linux for Prima Publishing. Joe welcomes your questions, comments, or ideas for future articles on DocBook and can be reached at jbrockmeier@earthlink.net .</p></div><div class="text-center mt-3 text-grey">
转载请注明原文地址:https://www.9cbs.com/read-26592.html</div><div class="plugin d-flex justify-content-center mt-3"></div><hr><div class="row"><div class="col-lg-12 text-muted mt-2"><i class="icon-tags mr-2"></i><span class="badge border border-secondary mr-2"><h2 class="h6 mb-0 small"><a class="text-secondary" href="tag-2.html">9cbs</a></h2></span></div></div></div></div><div class="card card-postlist border-white shadow"><div class="card-body"><div class="card-title"><div class="d-flex justify-content-between"><div><b>New Post</b>(<span class="posts">0</span>)
</div><div></div></div></div><ul class="postlist list-unstyled">
</ul></div></div><div class="d-none threadlist"><input type="checkbox" name="modtid" value="26592" checked /></div></div></div></div></div><footer class="text-muted small bg-dark py-4 mt-3" id="footer"><div class="container"><div class="row"><div class="col">CopyRight © 2020 All Rights Reserved
</div><div class="col text-right">Processed:
<b>0.051</b>, SQL:
<b>9</b></div></div></div></footer><script src="./lang/en-us/lang.js?2.2.0"></script><script src="view/js/jquery.min.js?2.2.0"></script><script src="view/js/popper.min.js?2.2.0"></script><script src="view/js/bootstrap.min.js?2.2.0"></script><script src="view/js/xiuno.js?2.2.0"></script><script src="view/js/bootstrap-plugin.js?2.2.0"></script><script src="view/js/async.min.js?2.2.0"></script><script src="view/js/form.js?2.2.0"></script><script>
var debug = DEBUG = 0;
var url_rewrite_on = 1;
var url_path = './';
var forumarr = {"1":"Tech"};
var fid = 1;
var uid = 0;
var gid = 0;
xn.options.water_image_url = 'view/img/water-small.png';
</script><script src="view/js/wellcms.js?2.2.0"></script><a class="scroll-to-top rounded" href="javascript:void(0);"><i class="icon-angle-up"></i></a><a class="scroll-to-bottom rounded" href="javascript:void(0);" style="display: inline;"><i class="icon-angle-down"></i></a></body></html><script>
var forum_url = 'list-1.html';
var safe_token = '3SYDHhw8cmHkaF7MLf_2F2oMBidgtQBcKp2Gr2l9kwzKgL2DBq_2Btv6l9JLY3MPEuZaGmgc7o02buG2eSKX4h6K5Q_3D_3D';
var body = $('body');
body.on('submit', '#form', function() {
var jthis = $(this);
var jsubmit = jthis.find('#submit');
jthis.reset();
jsubmit.button('loading');
var postdata = jthis.serializeObject();
$.xpost(jthis.attr('action'), postdata, function(code, message) {
if(code == 0) {
location.reload();
} else {
$.alert(message);
jsubmit.button('reset');
}
});
return false;
});
function resize_image() {
var jmessagelist = $('div.message');
var first_width = jmessagelist.width();
jmessagelist.each(function() {
var jdiv = $(this);
var maxwidth = jdiv.attr('isfirst') ? first_width : jdiv.width();
var jmessage_width = Math.min(jdiv.width(), maxwidth);
jdiv.find('img, embed, iframe, video').each(function() {
var jimg = $(this);
var img_width = this.org_width;
var img_height = this.org_height;
if(!img_width) {
var img_width = jimg.attr('width');
var img_height = jimg.attr('height');
this.org_width = img_width;
this.org_height = img_height;
}
if(img_width > jmessage_width) {
if(this.tagName == 'IMG') {
jimg.width(jmessage_width);
jimg.css('height', 'auto');
jimg.css('cursor', 'pointer');
jimg.on('click', function() {
});
} else {
jimg.width(jmessage_width);
var height = (img_height / img_width) * jimg.width();
jimg.height(height);
}
}
});
});
}
function resize_table() {
$('div.message').each(function() {
var jdiv = $(this);
jdiv.find('table').addClass('table').wrap('<div class="table-responsive"></div>');
});
}
$(function() {
resize_image();
resize_table();
$(window).on('resize', resize_image);
});
var jmessage = $('#message');
jmessage.on('focus', function() {if(jmessage.t) { clearTimeout(jmessage.t); jmessage.t = null; } jmessage.css('height', '6rem'); });
jmessage.on('blur', function() {jmessage.t = setTimeout(function() { jmessage.css('height', '2.5rem');}, 1000); });
$('#nav li[data-active="fid-1"]').addClass('active');
</script>
