| blob | 5f7cb34e53266f33146555f87b809cd39f0c2f2c |
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
204 document.
205 </para>
206 <para>
207 The final term you'll need to know when writing simple
210 DTD defines the flavor of SGML a given document is written
211 in. It lists all the legal tag names, like <sgmltag
214 how those tags are allowed to be used together. For
215 example, it doesn't make sense to put a <sgmltag
218 the reverse.
219 </para>
220 <para>
221 The DTD thus defines the legal structure of the document.
222 It also declares which attributes can be used with which
223 tags. The SGML processing system can use the DTD to make
224 sure the document is laid out properly before attempting
225 to process it. SGML-aware text editors like <link
227 guide you while you write, offering you choices about
228 which tags you can add in different places in the
229 document, and beeping at you when you try to add a tag
230 where it doesn't belong.
231 </para>
232 <para>
233 Generally, you will declare which DTD you want to use as
234 the first line of your SGML document. In the case of
235 DocBook, you will use something like this:
239 </para>
240 <para>
241 Note that you must specify your toplevel element inside
242 the doctype declaration. If you were writing an article
243 rather than a book, you might use this declaration instead:
246 ...
248 </para>
249 </sect3>
253 <para>
254 Once you're comfortable with SGML, creating a DocBook
255 document is quite simple and straightforward. Even
256 though DocBook contains over 300 different tags, you can
257 usually get by with only a small subset of those tags.
258 Most of them are for inline formatting, rather than for
259 document structuring. Furthermore, the common tags have
260 short, intuitive names.
261 </para>
262 <para>
263 Below is a (completely nonsensical) example to illustrate
264 how a simple document might be laid out. Notice that all
268 mandatory, but is a good habit to get into, as DocBook is
269 commonly converted into HTML, with a separate generated
274 attribute, the processor will typically name the file
275 accordingly. Thus, the below document might result in
279 </para>
280 <para>
283 denote SGML comments. SGML processors will completely
284 ignore anything between these markers, similar to
286 source code.
287 </para>
289 <!-- Encase the following SGML excerpt inside a CDATA
290 block so we don't have to bother converting all
291 brackets to entities
292 -->
293 <programlisting>
294 <![CDATA[
297 <bookinfo>
299 </bookinfo>
304 <!-- This section contains only one major topic -->
307 <para>
308 Blobs are often mistaken for ice cubes and rain
309 puddles...
310 </para>
311 </sect1>
313 <!-- This section contains embedded sub-sections -->
316 <para>
317 A Gribble is a cute, unassuming little fellow...
318 </para>
322 <para>
323 When left without food for several days...
324 </para>
325 </sect2>
329 <para>
330 Most Gribbles have a shock of white fur running from...
331 </para>
332 </sect2>
333 </sect1>
334 </chapter>
342 <para>
343 When most poets think of Dretch Pools, they tend to...
344 </para>
345 </sect>
346 </chapter>
347 </book>
348 ]]>
349 </programlisting>
350 </sect3>
352 <sect3>
354 <para>
355 Once you get used to the syntax of SGML, the next hurdle
356 in writing DocBook documentation is to learn the many
357 DocBook-specific tag names, and when to use them. DocBook
358 was created for technical documentation, and as such, the
359 tag names and document structure are slanted towards the
360 needs of such documentation.
361 </para>
362 <para>
363 To cover its target audience, DocBook declares a wide
364 variety of specialized tags, including tags for formatting
365 source code (with somewhat of a C/C++ bias), computer
366 prompts, GUI application features, keystrokes, and so on.
367 DocBook also includes tags for universal formatting needs,
368 like headers, footnotes, tables, and graphics.
369 </para>
370 <para>
371 We won't cover all of these elements here (over 300
372 DocBook tags exist!), but we will cover the basics. To
373 learn more about the other tags, check out the official
374 DocBook guide, at <ulink
376 see how they are used in practice, download the SGML
377 source for this manual (the Wine Developer Guide) and
378 browse through it, comparing it to the generated HTML (or
379 PostScript or PDF).
380 </para>
381 <para>
382 There are often many correct ways to mark up a given piece
383 of text, and you may have to make guesses about which tag
384 to use. Sometimes you'll have to make compromises.
385 However, remember that it is possible to further <link
387 the SGML processors. If you don't like the way a certain
388 tag looks in HTML, that doesn't mean you should choose a
389 different tag based on its output formatting. The
390 processing stylesheets can be altered to fix the
391 formatting of that same tag everywhere in the document
392 (not just in the place you're working on). For example,
393 if you're frustrated that the <sgmltag
395 any formatting by default, you should fix the stylesheets,
396 not change the valid <sgmltag
399 </para>
400 <para>
401 Here are the common SGML elements:
402 </para>
404 <variablelist>
406 <varlistentry>
408 <listitem>
409 <para>
410 The book is the most common toplevel element, and is
411 probably the one you should use for your document.
412 </para>
413 </listitem>
414 </varlistentry>
415 <varlistentry>
417 <listitem>
418 <para>
419 If you want to group more than one book into a
420 single unit, you can place them all inside a set.
421 This is useful when you want to bundle up
422 documentation in alternate ways. We do this with
423 the Wine documentation, using a <sgmltag
425 into a single directory (see
428 put each Wine guide into a separate directory (see
430 etc.).
431 </para>
432 </listitem>
433 </varlistentry>
434 <varlistentry>
436 <listitem>
437 <para>
439 element includes a single entire chapter of the
440 book.
441 </para>
442 </listitem>
443 </varlistentry>
444 <varlistentry>
446 <listitem>
447 <para>
448 If the chapters in your book fall into major
449 categories or groupings (as in the Wine Developer
450 Guide), you can place each collection of chapters
452 element.
453 </para>
454 </listitem>
455 </varlistentry>
456 <varlistentry>
458 <listitem>
459 <para>
460 DocBook has many section elements to divide the
461 contents of a chapter into smaller chunks. The
462 encouraged approach is to use the numbered section
468 These tags must be nested in order: you can't place
471 You have to nest the <sgmltag
474 Documents with these explicit section groupings are
475 easier for SGML processors to deal with, and lead to
476 better organized documents. DocBook also supplies a
478 which you can nest inside itself, but its use is
479 discouraged in favor of the numbered section tags.
480 </para>
481 </listitem>
482 </varlistentry>
483 <varlistentry>
485 <listitem>
486 <para>
487 The title of a book, chapter, part, section, etc.
488 In most of the major structural elements, like
491 various section tags, <sgmltag
493 other elements like <sgmltag
496 </para>
497 </listitem>
498 </varlistentry>
499 <varlistentry>
501 <listitem>
502 <para>
503 The basic unit of text is the paragraph, represented
505 This is probably the tag you'll use most often. In
506 fact, in a simple document, you can probably get
507 away with using only <sgmltag
512 </para>
513 </listitem>
514 </varlistentry>
515 <varlistentry>
517 <listitem>
518 <para>
519 For shorter, more targeted documents, like topic
520 pieces and whitepapers, you can use <sgmltag
522 element.
523 </para>
524 </listitem>
525 </varlistentry>
526 </variablelist>
528 <variablelist>
530 <varlistentry>
532 <listitem>
533 <para>
534 The name of a file. You can optionally set the
539 filename.
540 </para>
541 </listitem>
542 </varlistentry>
543 <varlistentry>
545 <listitem>
546 <para>
547 Literal text entered by the user.
548 </para>
549 </listitem>
550 </varlistentry>
551 <varlistentry>
553 <listitem>
554 <para>
555 Literal text output by the computer.
556 </para>
557 </listitem>
558 </varlistentry>
559 <varlistentry>
561 <listitem>
562 <para>
563 A catch-all element for literal computer data. Its
564 use is somewhat vague; try to use a more specific
565 tag if possible, like <sgmltag
568 </para>
569 </listitem>
570 </varlistentry>
571 <varlistentry>
573 <listitem>
574 <para>
575 An inline quotation. This tag typically inserts
576 quotation marks for you, so you would write <sgmltag
579 than "This is a quote". This usage may be a little
580 bulkier, but it does allow for automated formatting
581 of all quoted material in the document. Thus, if
582 you wanted all quotations to appear in italic, you
583 could make the change once in your stylesheet,
584 rather than doing a search and replace throughout
585 the document. For larger chunks of quoted text, you
586 can use <sgmltag
588 </para>
589 </listitem>
590 </varlistentry>
591 <varlistentry>
593 <listitem>
594 <para>
595 Insert a side note for the reader. By default, the
596 SGML processor usually prefixes the content with
597 "Note:". You can change this text by adding a
599 Thus, to add a visible FIXME comment to the
600 documentation, you might write:
601 </para>
602 <programlisting>
603 <![CDATA[
604 <note>
607 </note>
608 ]]></programlisting>
609 <para>
610 The results will look something like this:
611 </para>
612 <note>
615 </note>
616 </listitem>
617 </varlistentry>
618 <varlistentry>
620 <listitem>
621 <para>
622 Used for inserting SGML tags, etc., into a SGML
623 document without resorting to a lot of entity
624 quoting, e.g., &lt;. You can change the
625 appearance of the text with the <sgmltag
627 common values of this are
634 for examples.
635 </para>
636 </listitem>
637 </varlistentry>
638 <varlistentry>
640 <listitem>
641 <para>
642 The text used for a computer prompt, for example a
643 shell prompt, or command-line application prompt.
644 </para>
645 </listitem>
646 </varlistentry>
647 <varlistentry>
649 <listitem>
650 <para>
651 Meta-text that should be replaced by the user, not
652 typed in literally, e.g., in command descriptions
654 </para>
655 </listitem>
656 </varlistentry>
657 <varlistentry>
659 <listitem>
660 <para>
661 A programming constant, e.g.,
663 </para>
664 </listitem>
665 </varlistentry>
666 <varlistentry>
668 <listitem>
669 <para>
670 A symbolic value replaced, for example, by a
671 pre-processor. This applies primarily to C macros,
672 but may have other uses. Use the <sgmltag
675 appropriate.
676 </para>
677 </listitem>
678 </varlistentry>
679 <varlistentry>
681 <listitem>
682 <para>
683 A programming function name.
684 </para>
685 </listitem>
686 </varlistentry>
687 <varlistentry>
689 <listitem>
690 <para>
691 Programming language parameters you pass with a
692 function.
693 </para>
694 </listitem>
695 </varlistentry>
696 <varlistentry>
698 <listitem>
699 <para>
700 Parameters you pass to a command-line executable.
701 </para>
702 </listitem>
703 </varlistentry>
704 <varlistentry>
706 <listitem>
707 <para>
708 Variable name, typically in a programming language.
709 </para>
710 </listitem>
711 </varlistentry>
712 <varlistentry>
714 <listitem>
715 <para>
716 Programming language types, e.g., from a typedef
717 definition. May have other uses, too.
718 </para>
719 </listitem>
720 </varlistentry>
721 <varlistentry>
723 <listitem>
724 <para>
727 </para>
728 </listitem>
729 </varlistentry>
730 <varlistentry>
732 <listitem>
733 <para>
735 </para>
736 </listitem>
737 </varlistentry>
738 <varlistentry>
740 <listitem>
741 <para>
744 </para>
745 </listitem>
746 </varlistentry>
747 <varlistentry>
749 <listitem>
750 <para>
752 </para>
753 </listitem>
754 </varlistentry>
755 <varlistentry>
757 <listitem>
758 <para>
759 A generic catch-all for system-related things, like
760 OS names, computer names, system resources, etc.
761 </para>
762 </listitem>
763 </varlistentry>
764 <varlistentry>
766 <listitem>
767 <para>
768 An email address. The SGML processor will typically
769 add extra formatting characters, and even a
771 Usage: <sgmltag
774 </para>
775 </listitem>
776 </varlistentry>
777 <varlistentry>
779 <listitem>
780 <para>
781 Special emphasis for introducing a new term. Can
782 also be linked to a <sgmltag
784 desired.
785 </para>
786 </listitem>
787 </varlistentry>
788 </variablelist>
790 <variablelist>
792 <varlistentry>
794 <listitem>
795 <para>
796 For bulleted lists, no numbering. You can tweak the
797 layout with SGML attributes.
798 </para>
799 </listitem>
800 </varlistentry>
801 <varlistentry>
803 <listitem>
804 <para>
805 A numbered list; the SGML processor will insert the
806 numbers for you. You can suggest numbering styles
807 with the <sgmltag
809 </para>
810 </listitem>
811 </varlistentry>
812 <varlistentry>
814 <listitem>
815 <para>
816 A very simple list of items, often inlined. Control
817 the layout with the <sgmltag
819 </para>
820 </listitem>
821 </varlistentry>
822 <varlistentry>
824 <listitem>
825 <para>
826 A list of terms with definitions or descriptions,
827 like this very list!
828 </para>
829 </listitem>
830 </varlistentry>
831 </variablelist>
833 <variablelist>
835 <varlistentry>
837 <listitem>
838 <para>
839 Quote a block of source code. Typically highlighted
840 in the output and set off from normal text.
841 </para>
842 </listitem>
843 </varlistentry>
844 <varlistentry>
846 <listitem>
847 <para>
848 Quote a block of visible computer output, like the
849 output of a command or chunks of debug logs.
850 </para>
851 </listitem>
852 </varlistentry>
853 </variablelist>
855 <variablelist>
857 <varlistentry>
859 <listitem>
860 <para>
861 Generic hypertext link, used for pointing to other
862 sections within the current document. You supply
863 the visible text for the link, plus the name of the <sgmltag
865 element that you want to link to. For example:
867 ...
869 ...</programlisting>
870 </para>
871 </listitem>
872 </varlistentry>
873 <varlistentry>
875 <listitem>
876 <para>
877 In-document hyperlink that can generate its own
878 text. Similar to the <sgmltag
881 attribute to specify which target element you want
882 to jump to:
883 </para>
884 <para>
886 ...
888 ...</programlisting>
889 </para>
890 <para>
891 By default, most SGML processors will autogenerate
892 some generic text for the <sgmltag
896 attribute to grab the visible text content of the
897 hyperlink from another element:
898 </para>
899 <para>
901 ...
904 ...</programlisting>
905 </para>
906 <para>
907 This would create a link to the
909 displaying the text of the
911 hyperlink. Most often, you'll add an <sgmltag
914 section you're linking to, as above, in which case
915 the SGML processor will use the target's title text
916 for the link text.
917 </para>
918 <para>
919 Alternatively, you can use an <sgmltag
921 the target element tag to specify the link text:
922 </para>
924 <note>
925 <para>
927 empty element. You don't need a closing tag for
928 it (this is defined in the DTD). In SGML
929 documents, you should use the form <sgmltag
931 documents you should use
933 </para>
934 </note>
935 </listitem>
936 </varlistentry>
937 <varlistentry>
939 <listitem>
940 <para>
941 An invisible tag, used for inserting <sgmltag
943 document to link to arbitrary places (i.e., when
944 it's not close enough to link to the top of an
945 element).
946 </para>
947 </listitem>
948 </varlistentry>
949 <varlistentry>
951 <listitem>
952 <para>
953 Hyperlink in URL form, e.g., <ulink
955 </para>
956 </listitem>
957 </varlistentry>
958 <varlistentry>
960 <listitem>
961 <para>
962 Indirect hyperlink; can be used for linking to
963 external documents. Not often used in practice.
964 </para>
965 </listitem>
966 </varlistentry>
967 </variablelist>
968 </sect3>
970 <sect3>
972 <para>
973 How to split an SGML document into multiple files...
974 </para>
975 </sect3>
976 </sect2>
981 <para>
982 You can write SGML/DocBook documents in any text editor you
983 might find (although as we'll find in <xref
985 this task than others). However, if you want to convert
986 those documents into a more friendly form for reading, such
987 as HTML, PostScript, or PDF, you will need a working SGML
988 environment. This section attempts to lay out the various
989 SGML rendering systems, and how they are set up on the
990 popular Linux distributions.
991 </para>
993 <sect3>
995 <para>
996 Explain tools and methodologies..
997 </para>
998 </sect3>
1000 <sect3>
1002 <para>
1003 Explain tools and methodologies...
1004 </para>
1005 </sect3>
1007 <sect3>
1009 <para>
1010 Most Linux distributions have everything you need already
1011 bundled up in package form. Unfortunately, each
1012 distribution seems to handle its SGML environment
1013 differently, installing it into different paths, and
1014 naming its packages according to its own whims.
1015 </para>
1016 </sect3>
1018 <sect3>
1020 <para>
1021 List package names and install locations...
1022 </para>
1023 </sect3>
1025 <sect3>
1027 <para>
1028 List package names and install locations...
1029 </para>
1030 </sect3>
1031 </sect2>
1035 <para>
1036 Although you can write SGML documentation in any simple text
1037 editor, some editors provide extra support for entering SGML
1038 tags, and for verifying that the SGML you create is valid.
1039 SGML has been around for a long time, and many commercial
1040 editors exist for it; however, until recently open source
1041 SGML editors have been scarce.
1042 </para>
1043 <note>
1045 <para>
1046 List the available commercial and open source SGML
1047 editors.
1048 </para>
1049 </note>
1050 <para>
1051 The most commonly used open source SGML editor is Emacs,
1053 Emacs does not supply a GUI or WYSIWYG (What You See Is What
1054 You Get) interface, but it does provide many helpful
1055 shortcuts for creating SGML, as well as automatic
1056 formatting, validity checking, and the ability to create
1057 your own macros to simplify complex, repetitive actions.
1058 We'll touch briefly on each of these points.
1059 </para>
1060 <para>
1061 The first thing you need is a working installation of Emacs
1062 (or XEmacs), with the PSGML package. Most Linux
1063 distributions provide both as easy-to-install packages.
1064 </para>
1065 <para>
1066 Next, you'll need a working SGML environment. See <xref
1068 up.
1069 </para>
1070 </sect2>
1077 <para>
1078 How the build/make system works (makefiles, db2html,
1079 db2html-winehq, jade, stylesheets).
1080 </para>
1081 </sect3>
1085 <para>
1086 Things you can tweak, and how to do it (examples from
1087 default.dsl and winehq.dsl).
1088 </para>
1089 </sect3>
1093 <para>
1094 Explain make_winehq, rsync, etc.
1095 </para>
1096 </sect3>
1097 </sect2>
1098 </sect1>
1099 </chapter>
1101 <!-- Keep this comment at the end of the file
1102 Local variables:
1103 mode: sgml
1104 sgml-parent-document:("wine-doc.sgml" "set" "book" "part" "chapter" "")
1105 End:
1106 -->