| blob | c34436851b08f0e4d3592a899085064c5880dc9b |
8 <para>
10 </para>
11 <para>
13 </para>
15 <para>
16 To improve the documentation of the Wine API, just add
17 comments to the existing source. For example,
18 </para>
19 <screen>
20 /******************************************************************
21 * CopyMetaFileA (GDI32.23)
22 *
23 * Copies the metafile corresponding to hSrcMetaFile to either
24 * a disk file, if a filename is given, or to a new memory based
25 * metafile, if lpFileName is NULL.
26 *
27 * RETURNS
28 *
29 * Handle to metafile copy on success, NULL on failure.
30 *
31 * BUGS
32 *
33 * Copying to disk returns NULL even if successful.
34 */
35 HMETAFILE WINAPI CopyMetaFileA(
36 HMETAFILE hSrcMetaFile, /* handle of metafile to copy */
37 LPCSTR lpFilename /* filename if copying to a file */
38 ) { ... }
39 </screen>
40 <para>
43 </para>
44 <screen>
48 NAME
49 CopyMetaFileA (GDI32.23)
51 SYNOPSIS
52 HMETAFILE CopyMetaFileA
53 (
54 HMETAFILE hSrcMetaFile,
55 LPCSTR lpFilename
56 );
58 PARAMETERS
59 HMETAFILE hSrcMetaFile
60 Handle of metafile to copy.
62 LPCSTR lpFilename
63 Filename if copying to a file.
65 DESCRIPTION
66 Copies the metafile corresponding to hSrcMetaFile to
67 either a disk file, if a filename is given, or to a new
68 memory based metafile, if lpFileName is NULL.
70 RETURNS
71 Handle to metafile copy on success, NULL on failure.
73 BUGS
74 Copying to disk returns NULL even if successful.
76 SEE ALSO
79 sEx(3w)
80 </screen>
81 </sect1>
86 <para>
88 </para>
93 <para>
95 (<firstterm>Standard Generalized Markup
96 Language</firstterm>), a syntax for marking up the contents
97 of documents. HTML is another very common flavor of SGML;
98 DocBook markup looks very similar to HTML markup, although
99 the names of the markup tags differ.
100 </para>
102 <sect3>
105 <para>
106 SGML markup contains a number of syntactical elements that
107 serve different purposes in the markup. We'll run through
108 the basics here to make sure we're on the same page when
109 we refer to SGML semantics.
110 </para>
111 <para>
112 The basic currency of SGML is the
114 pair of angle brackets and the name of the tag. For
116 an SGML document as <sgmltag
118 that the immediately following text should be classified
119 according to the tag. In regular SGML, each opening tag
120 must have a matching end tag to show where the start tag's
121 contents end. End tags begin with
124 </para>
125 <para>
126 The combination of a start tag, contents, and an end tag
128 elements can be nested inside of each other, or contain
129 only text, or may be a combination of both text and other
130 elements, although in most cases it is better to limit
131 your elements to one or the other.
132 </para>
133 <para>
135 Language</firstterm>) specification, a modern subset of
136 the SGML specification, adds a so-called <firstterm>empty
137 tag</firstterm>, for elements that contain no text
138 content. The entire element is a single tag, ending with
141 tag style restricts you to XML DocBook processing, and
142 your document may no longer compile with SGML-only
143 processing systems.
144 </para>
145 <!-- *** Note: We could normally use the "emptytag"
146 attribute for XML empty tags, but that's only a recent
147 addition, and we don't want to screw up documents
148 generated against older stylesheets.
149 *** -->
150 <para>
151 Often a processing system will need more information about
152 an element than you can provide with just tags. SGML
155 this information. The most common use of attributes in
156 DocBook is giving specific elements a name, or an ID, so
157 you can refer to it from elsewhere. This ID can be used
158 for many things, including file-naming for HTML output,
159 hyper-linking to specific parts of the document, and even
160 pulling text from that element (see the <sgmltag
162 </para>
163 <para>
164 An SGML attribute appears inside the start tag, between
170 </para>
171 <para>
172 Notice that the contents of the attribute are enclosed in
173 quote marks. These quotes are optional in SGML, but
174 mandatory in XML. It's a good habit to use quotes, as it
175 will make it much easier to migrate your documents to an
176 XML processing system later on.
177 </para>
178 <para>
179 You can also specify more than one attribute in a single
181 </para>
182 <para>
183 Another commonly used type of SGML markup is the
185 associate a block of text with a name. You declare the
186 entity once, at the beginning of your document, and can
187 invoke it as many times as you like throughout the
188 document. You can use entities as shorthand, or to make
189 it easier to maintain certain phrases in a central
190 location, or even to insert the contents of an entire file
191 into your document.
192 </para>
193 <para>
194 An entity in your document is always surrounded by the
196 entity you'll need sooner or later is the one for the
200 your document (as I am doing here), you must insert it
207 </para>
208 <para>
209 The final term you'll need to know when writing simple
212 DTD defines the flavor of SGML a given document is written
213 in. It lists all the legal tag names, like <sgmltag
216 how those tags are allowed to be used together. For
217 example, it doesn't make sense to put a <sgmltag
220 the reverse.
221 </para>
222 <para>
223 The DTD thus defines the legal structure of the document.
224 It also declares which attributes can be used with which
225 tags. The SGML processing system can use the DTD to make
226 sure the document is laid out properly before attempting
227 to process it. SGML-aware text editors like <link
229 guide you while you write, offering you choices about
230 which tags you can add in different places in the
231 document, and beeping at you when you try to add a tag
232 where it doesn't belong.
233 </para>
234 <para>
235 Generally, you will declare which DTD you want to use as
236 the first line of your SGML document. In the case of
237 DocBook, you will use something like this:
241 </para>
242 <para>
243 Note that you must specify your toplevel element inside
244 the doctype declaration. If you were writing an article
245 rather than a book, you might use this declaration instead:
248 ...
250 </para>
251 </sect3>
255 <para>
256 Once you're comfortable with SGML, creating a DocBook
257 document is quite simple and straightforward. Even
258 though DocBook contains over 300 different tags, you can
259 usually get by with only a small subset of those tags.
260 Most of them are for inline formatting, rather than for
261 document structuring. Furthermore, the common tags have
262 short, intuitive names.
263 </para>
264 <para>
265 Below is a (completely nonsensical) example to illustrate
266 how a simple document might be laid out. Notice that all
270 mandatory, but is a good habit to get into, as DocBook is
271 commonly converted into HTML, with a separate generated
276 attribute, the processor will typically name the file
277 accordingly. Thus, the below document might result in
281 </para>
282 <para>
285 denote SGML comments. SGML processors will completely
286 ignore anything between these markers, similar to
288 source code.
289 </para>
291 <!-- Encase the following SGML excerpt inside a CDATA
292 block so we don't have to bother converting all
293 brackets to entities
294 -->
295 <programlisting>
296 <![CDATA[
299 <bookinfo>
301 </bookinfo>
306 <!-- This section contains only one major topic -->
309 <para>
310 Blobs are often mistaken for ice cubes and rain
311 puddles...
312 </para>
313 </sect1>
315 <!-- This section contains embedded sub-sections -->
318 <para>
319 A Gribble is a cute, unassuming little fellow...
320 </para>
324 <para>
325 When left without food for several days...
326 </para>
327 </sect2>
331 <para>
332 Most Gribbles have a shock of white fur running from...
333 </para>
334 </sect2>
335 </sect1>
336 </chapter>
344 <para>
345 When most poets think of Dretch Pools, they tend to...
346 </para>
347 </sect>
348 </chapter>
349 </book>
350 ]]>
351 </programlisting>
352 </sect3>
354 <sect3>
356 <para>
357 Once you get used to the syntax of SGML, the next hurdle
358 in writing DocBook documentation is to learn the many
359 DocBook-specific tag names, and when to use them. DocBook
360 was created for technical documentation, and as such, the
361 tag names and document structure are slanted towards the
362 needs of such documentation.
363 </para>
364 <para>
365 To cover its target audience, DocBook declares a wide
366 variety of specialized tags, including tags for formatting
367 source code (with somewhat of a C/C++ bias), computer
368 prompts, GUI application features, keystrokes, and so on.
369 DocBook also includes tags for universal formatting needs,
370 like headers, footnotes, tables, and graphics.
371 </para>
372 <para>
373 We won't cover all of these elements here (over 300
374 DocBook tags exist!), but we will cover the basics. To
375 learn more about the other tags, check out the official
376 DocBook guide, at <ulink
378 see how they are used in practice, download the SGML
379 source for this manual (the Wine Developer Guide) and
380 browse through it, comparing it to the generated HTML (or
381 PostScript or PDF).
382 </para>
383 <para>
384 There are often many correct ways to mark up a given piece
385 of text, and you may have to make guesses about which tag
386 to use. Sometimes you'll have to make compromises.
387 However, remember that it is possible to further <link
389 the SGML processors. If you don't like the way a certain
390 tag looks in HTML, that doesn't mean you should choose a
391 different tag based on its output formatting. The
392 processing stylesheets can be altered to fix the
393 formatting of that same tag everywhere in the document
394 (not just in the place you're working on). For example,
395 if you're frustrated that the <sgmltag
397 any formatting by default, you should fix the stylesheets,
398 not change the valid <sgmltag
401 </para>
402 <para>
403 Here are the common SGML elements:
404 </para>
406 <variablelist>
408 <varlistentry>
410 <listitem>
411 <para>
412 The book is the most common toplevel element, and is
413 probably the one you should use for your document.
414 </para>
415 </listitem>
416 </varlistentry>
417 <varlistentry>
419 <listitem>
420 <para>
421 If you want to group more than one book into a
422 single unit, you can place them all inside a set.
423 This is useful when you want to bundle up
424 documentation in alternate ways. We do this with
425 the Wine documentation, using a <sgmltag
427 into a single directory (see
430 put each Wine guide into a separate directory (see
432 etc.).
433 </para>
434 </listitem>
435 </varlistentry>
436 <varlistentry>
438 <listitem>
439 <para>
441 element includes a single entire chapter of the
442 book.
443 </para>
444 </listitem>
445 </varlistentry>
446 <varlistentry>
448 <listitem>
449 <para>
450 If the chapters in your book fall into major
451 categories or groupings (as in the Wine Developer
452 Guide), you can place each collection of chapters
454 element.
455 </para>
456 </listitem>
457 </varlistentry>
458 <varlistentry>
460 <listitem>
461 <para>
462 DocBook has many section elements to divide the
463 contents of a chapter into smaller chunks. The
464 encouraged approach is to use the numbered section
470 These tags must be nested in order: you can't place
473 You have to nest the <sgmltag
476 Documents with these explicit section groupings are
477 easier for SGML processors to deal with, and lead to
478 better organized documents. DocBook also supplies a
480 which you can nest inside itself, but its use is
481 discouraged in favor of the numbered section tags.
482 </para>
483 </listitem>
484 </varlistentry>
485 <varlistentry>
487 <listitem>
488 <para>
489 The title of a book, chapter, part, section, etc.
490 In most of the major structural elements, like
493 various section tags, <sgmltag
495 other elements like <sgmltag
498 </para>
499 </listitem>
500 </varlistentry>
501 <varlistentry>
503 <listitem>
504 <para>
505 The basic unit of text is the paragraph, represented
507 This is probably the tag you'll use most often. In
508 fact, in a simple document, you can probably get
509 away with using only <sgmltag
514 </para>
515 </listitem>
516 </varlistentry>
517 <varlistentry>
519 <listitem>
520 <para>
521 For shorter, more targeted documents, like topic
522 pieces and whitepapers, you can use <sgmltag
524 element.
525 </para>
526 </listitem>
527 </varlistentry>
528 </variablelist>
530 <variablelist>
532 <varlistentry>
534 <listitem>
535 <para>
536 The name of a file. You can optionally set the
541 filename.
542 </para>
543 </listitem>
544 </varlistentry>
545 <varlistentry>
547 <listitem>
548 <para>
549 Literal text entered by the user.
550 </para>
551 </listitem>
552 </varlistentry>
553 <varlistentry>
555 <listitem>
556 <para>
557 Literal text output by the computer.
558 </para>
559 </listitem>
560 </varlistentry>
561 <varlistentry>
563 <listitem>
564 <para>
565 A catch-all element for literal computer data. Its
566 use is somewhat vague; try to use a more specific
567 tag if possible, like <sgmltag
570 </para>
571 </listitem>
572 </varlistentry>
573 <varlistentry>
575 <listitem>
576 <para>
577 An inline quotation. This tag typically inserts
578 quotation marks for you, so you would write <sgmltag
581 than "This is a quote". This usage may be a little
582 bulkier, but it does allow for automated formatting
583 of all quoted material in the document. Thus, if
584 you wanted all quotations to appear in italic, you
585 could make the change once in your stylesheet,
586 rather than doing a search and replace throughout
587 the document. For larger chunks of quoted text, you
588 can use <sgmltag
590 </para>
591 </listitem>
592 </varlistentry>
593 <varlistentry>
595 <listitem>
596 <para>
597 Insert a side note for the reader. By default, the
598 SGML processor usually prefixes the content with
599 "Note:". You can change this text by adding a
601 Thus, to add a visible FIXME comment to the
602 documentation, you might write:
603 </para>
604 <programlisting>
605 <![CDATA[
606 <note>
609 </note>
610 ]]></programlisting>
611 <para>
612 The results will look something like this:
613 </para>
614 <note>
617 </note>
618 </listitem>
619 </varlistentry>
620 <varlistentry>
622 <listitem>
623 <para>
624 Used for inserting SGML tags, etc., into a SGML
625 document without resorting to a lot of entity
626 quoting, e.g., &lt;. You can change the
627 appearance of the text with the <sgmltag
629 common values of this are
636 for examples.
637 </para>
638 </listitem>
639 </varlistentry>
640 <varlistentry>
642 <listitem>
643 <para>
644 The text used for a computer prompt, for example a
645 shell prompt, or command-line application prompt.
646 </para>
647 </listitem>
648 </varlistentry>
649 <varlistentry>
651 <listitem>
652 <para>
653 Meta-text that should be replaced by the user, not
654 typed in literally, e.g., in command descriptions
656 </para>
657 </listitem>
658 </varlistentry>
659 <varlistentry>
661 <listitem>
662 <para>
663 A programming constant, e.g.,
665 </para>
666 </listitem>
667 </varlistentry>
668 <varlistentry>
670 <listitem>
671 <para>
672 A symbolic value replaced, for example, by a
673 pre-processor. This applies primarily to C macros,
674 but may have other uses. Use the <sgmltag
677 appropriate.
678 </para>
679 </listitem>
680 </varlistentry>
681 <varlistentry>
683 <listitem>
684 <para>
685 A programming function name.
686 </para>
687 </listitem>
688 </varlistentry>
689 <varlistentry>
691 <listitem>
692 <para>
693 Programming language parameters you pass with a
694 function.
695 </para>
696 </listitem>
697 </varlistentry>
698 <varlistentry>
700 <listitem>
701 <para>
702 Parameters you pass to a command-line executable.
703 </para>
704 </listitem>
705 </varlistentry>
706 <varlistentry>
708 <listitem>
709 <para>
710 Variable name, typically in a programming language.
711 </para>
712 </listitem>
713 </varlistentry>
714 <varlistentry>
716 <listitem>
717 <para>
718 Programming language types, e.g., from a typedef
719 definition. May have other uses, too.
720 </para>
721 </listitem>
722 </varlistentry>
723 <varlistentry>
725 <listitem>
726 <para>
729 </para>
730 </listitem>
731 </varlistentry>
732 <varlistentry>
734 <listitem>
735 <para>
737 </para>
738 </listitem>
739 </varlistentry>
740 <varlistentry>
742 <listitem>
743 <para>
746 </para>
747 </listitem>
748 </varlistentry>
749 <varlistentry>
751 <listitem>
752 <para>
754 </para>
755 </listitem>
756 </varlistentry>
757 <varlistentry>
759 <listitem>
760 <para>
761 A generic catch-all for system-related things, like
762 OS names, computer names, system resources, etc.
763 </para>
764 </listitem>
765 </varlistentry>
766 <varlistentry>
768 <listitem>
769 <para>
770 An email address. The SGML processor will typically
771 add extra formatting characters, and even a
773 Usage: <sgmltag
776 </para>
777 </listitem>
778 </varlistentry>
779 <varlistentry>
781 <listitem>
782 <para>
783 Special emphasis for introducing a new term. Can
784 also be linked to a <sgmltag
786 desired.
787 </para>
788 </listitem>
789 </varlistentry>
790 </variablelist>
792 <variablelist>
794 <varlistentry>
796 <listitem>
797 <para>
798 For bulleted lists, no numbering. You can tweak the
799 layout with SGML attributes.
800 </para>
801 </listitem>
802 </varlistentry>
803 <varlistentry>
805 <listitem>
806 <para>
807 A numbered list; the SGML processor will insert the
808 numbers for you. You can suggest numbering styles
809 with the <sgmltag
811 </para>
812 </listitem>
813 </varlistentry>
814 <varlistentry>
816 <listitem>
817 <para>
818 A very simple list of items, often inlined. Control
819 the layout with the <sgmltag
821 </para>
822 </listitem>
823 </varlistentry>
824 <varlistentry>
826 <listitem>
827 <para>
828 A list of terms with definitions or descriptions,
829 like this very list!
830 </para>
831 </listitem>
832 </varlistentry>
833 </variablelist>
835 <variablelist>
837 <varlistentry>
839 <listitem>
840 <para>
841 Quote a block of source code. Typically highlighted
842 in the output and set off from normal text.
843 </para>
844 </listitem>
845 </varlistentry>
846 <varlistentry>
848 <listitem>
849 <para>
850 Quote a block of visible computer output, like the
851 output of a command or chunks of debug logs.
852 </para>
853 </listitem>
854 </varlistentry>
855 </variablelist>
857 <variablelist>
859 <varlistentry>
861 <listitem>
862 <para>
863 Generic hypertext link, used for pointing to other
864 sections within the current document. You supply
865 the visible text for the link, plus the name of the <sgmltag
867 element that you want to link to. For example:
869 ...
871 ...</programlisting>
872 </para>
873 </listitem>
874 </varlistentry>
875 <varlistentry>
877 <listitem>
878 <para>
879 In-document hyperlink that can generate its own
880 text. Similar to the <sgmltag
883 attribute to specify which target element you want
884 to jump to:
885 </para>
886 <para>
888 ...
890 ...</programlisting>
891 </para>
892 <para>
893 By default, most SGML processors will autogenerate
894 some generic text for the <sgmltag
898 attribute to grab the visible text content of the
899 hyperlink from another element:
900 </para>
901 <para>
903 ...
906 ...</programlisting>
907 </para>
908 <para>
909 This would create a link to the
911 displaying the text of the
913 hyperlink. Most often, you'll add an <sgmltag
916 section you're linking to, as above, in which case
917 the SGML processor will use the target's title text
918 for the link text.
919 </para>
920 <para>
921 Alternatively, you can use an <sgmltag
923 the target element tag to specify the link text:
924 </para>
926 <note>
927 <para>
929 empty element. You don't need a closing tag for
930 it (this is defined in the DTD). In SGML
931 documents, you should use the form <sgmltag
933 documents you should use
935 </para>
936 </note>
937 </listitem>
938 </varlistentry>
939 <varlistentry>
941 <listitem>
942 <para>
943 An invisible tag, used for inserting <sgmltag
945 document to link to arbitrary places (i.e., when
946 it's not close enough to link to the top of an
947 element).
948 </para>
949 </listitem>
950 </varlistentry>
951 <varlistentry>
953 <listitem>
954 <para>
955 Hyperlink in URL form, e.g., <ulink
957 </para>
958 </listitem>
959 </varlistentry>
960 <varlistentry>
962 <listitem>
963 <para>
964 Indirect hyperlink; can be used for linking to
965 external documents. Not often used in practice.
966 </para>
967 </listitem>
968 </varlistentry>
969 </variablelist>
970 </sect3>
972 <sect3>
974 <para>
975 How to split an SGML document into multiple files...
976 </para>
977 </sect3>
978 </sect2>
983 <para>
984 You can write SGML/DocBook documents in any text editor you
985 might find (although as we'll find in <xref
987 this task than others). However, if you want to convert
988 those documents into a more friendly form for reading, such
989 as HTML, PostScript, or PDF, you will need a working SGML
990 environment. This section attempts to lay out the various
991 SGML rendering systems, and how they are set up on the
992 popular Linux distributions.
993 </para>
995 <sect3>
997 <para>
998 Explain tools and methodologies..
999 </para>
1000 </sect3>
1002 <sect3>
1004 <para>
1005 Explain tools and methodologies...
1006 </para>
1007 </sect3>
1009 <sect3>
1011 <para>
1012 Most Linux distributions have everything you need already
1013 bundled up in package form. Unfortunately, each
1014 distribution seems to handle its SGML environment
1015 differently, installing it into different paths, and
1016 naming its packages according to its own whims.
1017 </para>
1018 <para>
1019 The following packages seems to be sufficient for RedHat 7.1. You
1020 will want to be careful about the order in which you install the
1021 rpms.
1022 <itemizedlist>
1031 </itemizedlist>
1032 You can also use ghostscript to view the ps format output and
1033 Adobe Acrobat 4 to view the pdf file.
1034 </para>
1035 </sect3>
1037 <sect3>
1039 <para>
1040 List package names and install locations...
1041 </para>
1042 </sect3>
1044 <sect3>
1046 <para>
1047 List package names and install locations...
1048 </para>
1049 </sect3>
1050 </sect2>
1054 <para>
1055 Although you can write SGML documentation in any simple text
1056 editor, some editors provide extra support for entering SGML
1057 tags, and for verifying that the SGML you create is valid.
1058 SGML has been around for a long time, and many commercial
1059 editors exist for it; however, until recently open source
1060 SGML editors have been scarce.
1061 </para>
1062 <note>
1064 <para>
1065 List the available commercial and open source SGML
1066 editors.
1067 </para>
1068 </note>
1069 <para>
1070 The most commonly used open source SGML editor is Emacs,
1072 Emacs does not supply a GUI or WYSIWYG (What You See Is What
1073 You Get) interface, but it does provide many helpful
1074 shortcuts for creating SGML, as well as automatic
1075 formatting, validity checking, and the ability to create
1076 your own macros to simplify complex, repetitive actions.
1077 We'll touch briefly on each of these points.
1078 </para>
1079 <para>
1080 The first thing you need is a working installation of Emacs
1081 (or XEmacs), with the PSGML package. Most Linux
1082 distributions provide both as easy-to-install packages.
1083 </para>
1084 <para>
1085 Next, you'll need a working SGML environment. See <xref
1087 up.
1088 </para>
1089 </sect2>
1096 <para>
1097 How the build/make system works (makefiles, db2html,
1098 db2html-winehq, jade, stylesheets).
1099 </para>
1100 </sect3>
1104 <para>
1105 Things you can tweak, and how to do it (examples from
1106 default.dsl and winehq.dsl).
1107 </para>
1108 </sect3>
1112 <para>
1113 Explain make_winehq, rsync, etc.
1114 </para>
1115 </sect3>
1116 </sect2>
1117 </sect1>
1118 </chapter>
1120 <!-- Keep this comment at the end of the file
1121 Local variables:
1122 mode: sgml
1123 sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
1124 End:
1125 -->