Changeset 3352
- Timestamp:
- May 21, 2007, 11:42:25 AM (16 years ago)
- Location:
- trunk/doc/src/docbook
- Files:
-
- 3 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/src/docbook/developerdoc/write_docbook_doc.xml
r3348 r3352 102 102 <title>Getting started</title> 103 103 <para> 104 Before startwriting any documentation in BASE2 there are a couple of things, some104 Before writing any documentation in BASE2 there are a couple of things, some 105 105 rules and standards, to have in mind. 106 106 </para> … … 109 109 <para> 110 110 The source files of the documentation are located in 111 <filename class='directory'>base2root/doc/src/docbook</filename> 112 which is showed in 113 <xref linkend="write_docbook_doc.figures.fileorganization" /> 114 . The different parts of the documentation are organized into separate folders and 111 <filename class='directory'><base-dir>/doc/src/docbook</filename>. 112 The different parts of the documentation are organized into separate folders and 115 113 each one of the folders contains one index file and one file for each chapter in 116 114 that part. The index file joins the chapters, in current part/folder, together and … … 124 122 <mediaobject> 125 123 <imageobject> 126 <imagedata contentwidth="15cm" width="15cm" fileref="figures/fileorganization.png" format="PNG"></imagedata>124 <imagedata fileref="figures/fileorganization.png" format="PNG" /> 127 125 </imageobject> 128 126 </mediaobject> … … 132 130 <title>Create new chapter/file</title> 133 131 <para> 134 Each file in the documentation, except the index files, represents a chapter. 135 How to create a new chapter and include it in the text is described in 136 following items. 132 Most files in the documentation, except the index files, represents a chapter. 133 Here is how to create a new chapter and include it in the main documentation: 137 134 <orderedlist numeration='arabic' spacing='compact'> 138 135 <listitem> 139 136 <para> 140 Create a new XML-file in the folder of which partthe new chapter137 Create a new XML-file in the folder for the part where the new chapter 141 138 should be included. Give it a name that is quite similar to the 142 139 new chapter's title but use <userinput>_</userinput> instead of 143 blank space and keep it down to one or few words.140 blank space and keep it down to one or a few words. 144 141 </para> 145 142 </listitem> 146 143 <listitem> 147 144 <para> 148 Begin to write the chapter's body, it should look like 149 <xref linkend="write_docbook_doc.examples.chapterbody"/> 145 Begin to write the chapter's body, here is an example: 150 146 <example id="write_docbook_doc.examples.chapterbody"> 151 147 <title>Example of a chapter</title> … … 153 149 <?xml version="1.0" encoding="UTF-8"?> 154 150 <!DOCTYPE chapter PUBLIC 155 156 151 "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 152 "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd"> 157 153 158 154 <chapter id="<replaceable>example_chapter</replaceable>"> … … 181 177 </sect1> 182 178 </chapter> 183 179 </programlisting> 184 180 </example> 185 181 </para> … … 197 193 <listitem> 198 194 <para> 199 Next andlast step is to get the new chapter included in the documentation. This is done by including the file's name in195 The last step is to get the new chapter included in the documentation. This is done by including the file's name in 200 196 the file 201 197 <filename>index.xml</filename> 202 198 that's located in the current part's folder. 203 <xref linkend="write_docbook_doc.examples.include_chapter" />199 The following example 204 200 shows how the chapter that was created above is included in the user 205 201 documentation part. … … 246 242 <title>Controlling chunking</title> 247 243 <para> 248 We have configured docbook to create a new output file for249 each new <sgmltag class="starttag">chapter</sgmltag>250 and <sgmltag class="starttag">sect1</sgmltag>. In most cases this244 We have configured docbook to create a new subdirectory for each 245 <sgmltag class="starttag">chapter</sgmltag> and a new output file for each 246 <sgmltag class="starttag">sect1</sgmltag> tag. In most cases this 251 247 gives each page a relatively good size. Not too long and not too short. 252 248 However, if a chapter contains many small <sgmltag class="starttag">sect1</sgmltag> 253 249 sections (for example, <xref linkend="resources"/>), you end up with many 254 250 pages with just a few lines of text on each page. This is not so 255 good and can be avoided by adding a <sgmltag class="attribute">chunked ="0"</sgmltag>256 a ttribute to the chapter, for example:251 good and can be avoided by adding <sgmltag class="attribute">chunked="0"</sgmltag> 252 as an attribute to the <sgmltag class="starttag">chapter</sgmltag> tag, for example: 257 253 </para> 258 254 <programlisting> … … 261 257 <para> 262 258 This will stop the chunking of <sgmltag class="starttag">sect1</sgmltag> 263 sections in this chapter. On the other 259 sections in this chapter. 260 </para> 261 262 <para> 263 On the other 264 264 hand, if you have a <sgmltag class="starttag">sect1</sgmltag> 265 265 that contains many long <sgmltag class="starttag">sect2</sgmltag> 266 266 sections you might want to put each <sgmltag class="starttag">sect2</sgmltag> 267 section in a separate chunk . If you want to do this:267 section in a separate chunk: 268 268 </para> 269 269 <programlisting> … … 280 280 </title> 281 281 <para> 282 Common to all elements is that they have an id attribute that can have an unique value to identify the 283 element with. Most of the elements that are used inside the BASE2 documentation don't 282 Common to all elements is that they have an <sgmltag class="attribute">id</sgmltag> 283 attribute that can be used to identify the 284 element with. The value must be unique for the entire documentation. 285 Most of the elements that are used inside the BASE2 documentation don't 284 286 need to have an id if they don't are used in any cross references from other part of 285 287 the text. 286 288 </para> 287 289 <para> 288 There are howeversome elements that always should have the290 There are some elements that always should have the 289 291 <sgmltag class="attribute">id</sgmltag> 290 292 set. Which these elements are and how the 291 293 <sgmltag class="attribute">id</sgmltag> 292 should look like for each one of those is described below. All ids should be as294 should look like for each one of those is described below. All values should be as 293 295 short as possible and associated to the current element. The 294 296 <sgmltag class="attribute">id</sgmltag> … … 349 351 <title>Mark help texts</title> 350 352 <para> 353 This documentation is also use to create the help texts that show up 354 in the web client when clicking on the question mark icons. 351 355 The parts of the text that also should be used as help texts in the web must be 352 356 inside … … 362 366 <sgmltag class="starttag">helptext</sgmltag> 363 367 must be outside the 364 <sgmltag >para</sgmltag>368 <sgmltag class="starttag">para</sgmltag> 365 369 tag but inside a 366 <sgmltag>sect1</sgmltag> 367 tag to work properly. 370 <sgmltag class="starttag">sect</sgmltag> 371 tag to work properly. Don't put any <sgmltag class="starttag">sect</sgmltag> 372 tags inside the helptext. This will make the automatic chapter and section 373 numbering confused. 368 374 </para> 369 375 </note> … … 416 422 <programlisting> 417 423 <sect1> 418 419 420 421 422 423 424 424 <helptext external_id="<replaceable>helptexts.external.id</replaceable>" title="<replaceable>The title</replaceable>"> 425 <replaceable>The text that also should be used as a helptext in the program.</replaceable> 426 <seeother> 427 <other external_id="<replaceable>other.external.id</replaceable>"> 428 <replaceable>Related info here...</replaceable></other> 429 </seeother> 430 </helptext> 425 431 </sect1> 426 432 </programlisting> 427 433 </example> 428 434 … … 465 471 </varlistentry> 466 472 </variablelist> 473 474 <programlisting> 475 <seeother> 476 <other external_id="userpreferences.password">Change password</other> 477 <other external_id="userpreferences.other">Other information</other> 478 </seeother> 479 </programlisting> 480 481 <para> 482 We recommend that you place the links at the end of the 483 help text section. The links will not show up in the HTML or PDF version. 484 </para> 467 485 </sect3> 468 486 469 487 <sect3 id="write_docbook_doc.begin.helptext.import"> 470 488 <title>Import help texts into BASE</title> 489 471 490 <para> 472 491 Import the generated XML-file manually by uploading it from the … … 498 517 <para> 499 518 Those who have checked out the documentation source from repository or got the 500 source from a distribution package needs to compile it to get the pdf and html519 source from a distribution package needs to compile it to get the PDF and HTML 501 520 documentation files. The compilation of the documentation source requires, beside Ant, that the XML-parser 502 Xsltproc is installed on the local computer. XsltProc and how it is installed, can503 be found at521 Xsltproc is installed on the local computer. More information about 522 XsltProc and how it is installed, can be found at 504 523 <ulink url="http://xmlsoft.org/XSLT/index.html"></ulink>. 505 524 </para> … … 521 540 pages/files. The other format is a PDF-file that are most useful for printing 522 541 and distribution. Those two types of output are generated with the ant-target: 523 <command>ant docbook</command> 524 . This documentation is also generated with 525 <command>ant dist</command> 526 , which will put the output files in the right location for distribution with 542 <command>ant docbook</command>. This documentation is also generated with 543 <command>ant dist</command>, which will put the output files in the right location for distribution with 527 544 BASE 2. 528 545 </para> … … 588 605 <sgmltag class="starttag">para</sgmltag> 589 606 </entry> 590 <entry> </entry>607 <entry>Used almost everywhere around real text.</entry> 591 608 </row> 592 609 <row> … … 623 640 <entry>Fourth level section</entry> 624 641 <entry> 625 <sgmltag class="starttag">sect 3</sgmltag>642 <sgmltag class="starttag">sect4</sgmltag> 626 643 </entry> 627 644 <entry></entry> … … 630 647 <entry>Fith level section</entry> 631 648 <entry> 632 <sgmltag class="starttag">sect 3</sgmltag>649 <sgmltag class="starttag">sect5</sgmltag> 633 650 </entry> 634 651 <entry></entry> … … 639 656 640 657 <sect3 id="write_docbook_doc.usedtags.text.keywords"> 641 <title> Markup special words and phrases</title>658 <title>Code elements</title> 642 659 <para> 643 660 These elements should be used to mark up words and phrases that have a special 644 meaning, like method names, class names and user inputs just to mention some. 661 meaning in a coding environment, like method names, class names and 662 user inputs, etc. 645 663 </para> 646 664 <informaltable frame="none"> … … 662 680 <sgmltag class="starttag">classname</sgmltag> 663 681 </entry> 664 <entry> </entry>682 <entry>The name of a (Java) class.</entry> 665 683 </row> 666 684 <row> … … 669 687 <sgmltag class="starttag">userinput</sgmltag> 670 688 </entry> 671 <entry> </entry>689 <entry>Text that is entered by a user.</entry> 672 690 </row> 673 691 <row> … … 676 694 <sgmltag class="starttag">varname</sgmltag> 677 695 </entry> 678 <entry> </entry>696 <entry>The name of a variable in a program.</entry> 679 697 </row> 680 698 <row> … … 683 701 <sgmltag class="starttag">constant</sgmltag> 684 702 </entry> 685 <entry> </entry>703 <entry>The name of a variable in a program.</entry> 686 704 </row> 687 705 <row> … … 778 796 … 779 797 <methodsynopsis language="java"> 780 781 782 783 798 <modifier>public</modifier> 799 <type>Plugin.MainType</type> 800 <methodname>getMainType</methodname> 801 <void /> 784 802 </methodsynopsis> 785 803 … 786 804 </programlisting> 787 805 </example> 788 806 <example id="write_docbook_doc.examples.methodimpl1"> … … 793 811 … 794 812 <methodsynopsis language="java"> 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 813 <modifier>public</modifier> 814 <void /> 815 <methodname>init</methodname> 816 <methodparam> 817 <type>SessionControl</type> 818 <parameter>sc</parameter> 819 </methodparam> 820 <methodparam> 821 <type>ParameterValues</type> 822 <parameter>configuration</parameter> 823 </methodparam> 824 <methodparam> 825 <type>ParameterValues</type> 826 <parameter>job</parameter> 827 </methodparam> 810 828 </methodsynopsis> 811 829 … 812 830 </programlisting> 813 831 </example> 814 832 … … 897 915 <imageobject> 898 916 <imagedata 899 scalefit="1"900 width="100%"901 917 fileref="figures/menuchoice.png" format="PNG" 902 918 /> … … 910 926 … 911 927 <menuchoice> 912 913 914 928 <guimenu>Administrate</guimenu> 929 <guisubmenu>Plugins</guisubmenu> 930 <guimenuitem>Types</guimenuitem> 915 931 </menuchoice> 916 932 … … … 935 951 otherwise the image won't be visible in the generated output files. 936 952 </para> 937 <warning> 938 <para> 939 When using images in docbook you will always have problems with scaling. 940 Since we are generating output for both HTML and PDF it is even worse. 941 What we have found to work is this: 942 943 <itemizedlist> 944 <listitem> 945 <para> 946 Scaling in HTML has been disabled. The images will always be the 947 same size as they actually are. Please, don't make the screenshots 948 too wide! 949 </para> 950 </listitem> 951 952 <listitem> 953 <para> 954 For small images, less than the width of the PDF page, 955 do not specify scaling factors or widths. We have configured PDF to 956 use 96dpi instead of 72dpi, so the images will appear almost 957 exactly as they do in the HTML version. 958 </para> 959 </listitem> 960 961 <listitem> 962 <para> 963 Images that are wider than the PDF page will be clipped. To 964 prevent this you must add the following attributes to the 965 <sgmltag class="starttag">imagedata</sgmltag> tag: 966 <code>scalefit="1" width="100%"</code> 967 </para> 968 </listitem> 969 970 <listitem> 971 <para> 972 If you still need to scale the image differently in the PDF use 973 the <sgmltag>width</sgmltag> and <sgmltag>depth</sgmltag> 974 attributes. 975 </para> 976 </listitem> 977 </itemizedlist> 978 </para> 979 </warning> 953 980 954 <example id="write_docbook_doc.examples.screenshot"> 981 955 <title>Screen-shot in the documentation</title> … … 1001 975 </programlisting> 1002 976 </example> 977 <warning> 978 <para> 979 When using images in docbook you will always have problems with image 980 resolution and scaling. Since we are generating output for both HTML 981 and PDF it is even worse. What we have found to work is this: 982 983 <itemizedlist> 984 <listitem> 985 <para> 986 The screenshots must be saved without any resolution information 987 in them, or with the resolution set to 96 dpi. We have configured PDF to 988 use 96 dpi instead of 72 dpi to make the HTML and PDF output 989 look as similar as possible. 990 </para> 991 </listitem> 992 993 <listitem> 994 <para> 995 Scaling in HTML has been disabled. The images will always be the 996 same size (number of pixels) as they actually are. Please, don't 997 make the screenshots too wide! 998 </para> 999 </listitem> 1000 1001 <listitem> 1002 <para> 1003 For small images, less than the width of the PDF page, 1004 do not specify scaling factors or widths. 1005 </para> 1006 </listitem> 1007 1008 <listitem> 1009 <para> 1010 Images that are wider than the PDF page will be clipped. To 1011 prevent this you must add the following attributes to the 1012 <sgmltag class="starttag">imagedata</sgmltag> tag: 1013 <code>scalefit="1" width="100%"</code>. This will scale down 1014 the image so that it fits the available width. 1015 </para> 1016 </listitem> 1017 1018 <listitem> 1019 <para> 1020 If you still need to scale the image differently in the PDF use 1021 the <sgmltag>width</sgmltag> and <sgmltag>depth</sgmltag> 1022 attributes. 1023 </para> 1024 </listitem> 1025 </itemizedlist> 1026 </para> 1027 </warning> 1003 1028 </sect2> 1004 1029 <sect2 id="write_docbook_doc.usedtags.examples"> … … 1010 1035 </para> 1011 1036 <warning> 1012 <para> 1013 More then 80 characters(including indention) in a row of program 1014 listings or other verbatim elements will risk to put the end of the row outside 1015 the text area. 1037 <title>Use spaces instead of tabs for indentation</title> 1038 <para> 1039 More then 80 characters in a row of program listings or 1040 other verbatim elements will risk to put the end of the 1041 row outside the text area. A tab is usually displayed as 8 spaces 1042 which will use up too much space. 1016 1043 </para> 1017 1044 </warning> … … 1024 1051 </para> 1025 1052 <programlisting> 1026 … 1027 <example id="net.sf.basedb.core.plugin.Plugin.getAbout"> 1028 <title>A typical implementation stores this information in a static field</title> 1029 <programlisting> 1053 … 1054 <example id="net.sf.basedb.core.plugin.Plugin.getAbout"> 1055 <title>A typical implementation stores this information 1056 in a static field</title> 1057 <programlisting> 1030 1058 private static final About about = new AboutImpl 1031 1059 ( … … 1044 1072 return about; 1045 1073 } 1046 1047 1048 1049 1074 </programlisting> 1075 </example> 1076 … 1077 </programlisting> 1050 1078 </example> 1051 1079 </sect2> … … 1181 1209 </varlistentry> 1182 1210 </variablelist> 1183 1211 </programlisting> 1184 1212 </example> 1185 1213 </sect2> … … 1236 1264 <ulink url="http://base.thep.lu.se">Base2's homepage</ulink> 1237 1265 … 1238 1266 </programlisting> 1239 1267 <para> 1240 1268 The first element will autogenerate the linked section's/chapter's title as a
Note: See TracChangeset
for help on using the changeset viewer.