Changeset 3268
- Timestamp:
- Apr 24, 2007, 5:37:11 PM (16 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/doc/src/docbook/developerdoc/write_docbook_doc.xml
r3265 r3268 54 54 </para> 55 55 <variablelist> 56 <title>Parts of the documentation</title>57 56 <varlistentry> 58 57 <term>Overview documentation</term> … … 218 217 <title> 219 218 The 220 < varname>id</varname>219 <sgmltag class="attribute">id</sgmltag> 221 220 attribute 222 221 </title> … … 229 228 <para> 230 229 There are however some elements that always should have an 231 < varname>id</varname>230 <sgmltag class="attribute">id</sgmltag> 232 231 . Which these elements are and how the 233 < varname>id</varname>232 <sgmltag class="attribute">id</sgmltag> 234 233 should look like for each one of those is described below. All ids should be as 235 234 short as possible and associated to the current element. The 236 < varname>id</varname>235 <sgmltag class="attribute">id</sgmltag> 237 236 shouldn't consist of other characters then lowercase a-z, 238 237 <userinput>_</userinput> … … 246 245 <para> 247 246 The chapter should have an 248 < varname>id</varname>247 <sgmltag class="attribute">id</sgmltag> 249 248 that is identical or almost identical to the chapter's title. 250 249 <synopsis>chapter_title</synopsis> … … 269 268 <para> 270 269 The naming of an example's 271 < varname>id</varname>270 <sgmltag class="attribute">id</sgmltag> 272 271 is a bit different compare to the chapter's and section's id. It 273 272 should begin with the chapter's id followed by … … 283 282 <para> 284 283 The figure's 285 < varname>id</varname>284 <sgmltag class="attribute">id</sgmltag> 286 285 should have the following layout 287 286 <synopsis>chapter_title.figures.figure_name</synopsis> … … 317 316 <varlistentry> 318 317 <term> 319 < varname>external_id</varname>318 <sgmltag class="attribute">id</sgmltag> 320 319 </term> 321 320 <listitem> … … 330 329 <varlistentry> 331 330 <term> 332 < varname>title</varname>331 <sgmltag class="attribute">id</sgmltag> 333 332 </term> 334 333 <listitem> … … 375 374 <title>Elements to use</title> 376 375 <para>Which docbook tags are used in the documentation and when to use what......</para> 376 <para> 377 There will not be any detailed explanation of the tags, instead the reader is 378 recommended to get more information from 379 <ulink url="http://www.docbook.org/tdg/en/html/docbook.html"> 380 docbook's documentation 381 </ulink> 382 or other references. 383 </para> 377 384 <sect2 id="write_docbook_doc.usedtags.text"> 378 385 <title>Text</title> 379 386 <para> 380 Here is described which tag to use for different kinds of format and text layout. 381 There will not be any detailed explanation of the tags, the reader is recommended to 382 get more information from 383 <ulink url="http://www.docbook.org/tdg/en/html/docbook.html"> 384 docbook's documentation 385 </ulink> 386 or other references instead. 387 </para> 388 387 Here are the most common elements that are used in the current documentation source 388 to give the text a layout in some kind. 389 </para> 390 <variablelist> 391 <varlistentry> 392 <term> 393 <sgmltag class="starttag">chapter</sgmltag> 394 </term> 395 <listitem> 396 <para> 397 Define a chapter. Read more about chapters in this document in the 398 <xref linkend="write_docbook_doc.begin" /> 399 </para> 400 </listitem> 401 </varlistentry> 402 <varlistentry> 403 <term> 404 <sgmltag class="starttag">sect1</sgmltag> 405 , 406 <sgmltag class="starttag">sect2</sgmltag> 407 , 408 <sgmltag class="starttag">sect3</sgmltag> 409 </term> 410 <listitem> 411 <para> 412 Different levels of subsections in the document, see 413 <xref linkend="write_docbook_doc.begin" /> 414 for more information how to implement them right. 415 </para> 416 </listitem> 417 </varlistentry> 418 <varlistentry> 419 <term> 420 <sgmltag class="starttag">title</sgmltag> 421 </term> 422 <listitem> 423 <para> 424 Define title-node in those elements that can have a title. 425 </para> 426 </listitem> 427 </varlistentry> 428 <varlistentry> 429 <term> 430 <sgmltag class="starttag">para</sgmltag> 431 </term> 432 <listitem> 433 <para> 434 Define a paragraph in the text. Required as a child node in many 435 different elements. 436 </para> 437 </listitem> 438 </varlistentry> 439 <varlistentry> 440 <term> 441 <sgmltag class="starttag">ulink</sgmltag> 442 </term> 443 <listitem> 444 <para> 445 Define an external link to the URL that is set in it's 446 <sgmltag class="attribute">url</sgmltag> 447 attribute. 448 </para> 449 </listitem> 450 </varlistentry> 451 <varlistentry> 452 <term> 453 <sgmltag class="starttag">xref</sgmltag> 454 </term> 455 <listitem> 456 <para> 457 Define a link inside this document. The 458 <sgmltag class="attribute">linkend</sgmltag> 459 attribute holds the id to the target element. 460 </para> 461 </listitem> 462 </varlistentry> 463 </variablelist> 464 389 465 <sect3 id="write_docbook_doc.usedtags.text.keywords"> 390 <title>Markup special words</title> 391 <para></para> 466 <title>Markup special words and phrases</title> 467 <para> 468 These elements should be used to mark up words and phrases that have a special 469 meaning, like method names, class names and user inputs just to mention some 470 examples. 471 </para> 472 <variablelist><varlistentry><term><sgmltag class="starttag">methodsynopsis</sgmltag></term><listitem><para></para></listitem></varlistentry> 473 <varlistentry><term><sgmltag class="starttag">modifier</sgmltag></term><listitem><para></para></listitem></varlistentry> 474 <varlistentry><term><sgmltag class="starttag">methodname</sgmltag></term><listitem><para></para></listitem></varlistentry> 475 <varlistentry><term><sgmltag class="starttag">methodparam</sgmltag></term><listitem><para></para></listitem></varlistentry> 476 <varlistentry><term><sgmltag class="starttag">type</sgmltag></term><listitem><para></para></listitem></varlistentry> 477 <varlistentry><term><sgmltag class="starttag">parameter</sgmltag></term><listitem><para></para></listitem></varlistentry> 478 <varlistentry><term><sgmltag class="starttag">classname</sgmltag></term><listitem><para></para></listitem></varlistentry> 479 <varlistentry><term><sgmltag class="starttag">userinput</sgmltag></term><listitem><para></para></listitem></varlistentry> 480 <varlistentry><term><sgmltag class="starttag">varname</sgmltag></term><listitem><para></para></listitem></varlistentry> 481 <varlistentry><term><sgmltag class="starttag">constant</sgmltag></term><listitem><para></para></listitem></varlistentry></variablelist> 482 </sect3> 483 <sect3 id="write_docbook_doc.usedtags.text.gui"> 484 <title>Gui elements</title> 485 <para> 486 There are alot of elements that symbolize the gui in a program. Following 487 list contains those which are used in this document. 488 </para> 489 <variablelist><varlistentry><term><sgmltag class="starttag">guibutton</sgmltag></term><listitem><para></para></listitem></varlistentry> 490 <varlistentry><term><sgmltag class="starttag">guilabel</sgmltag></term><listitem><para></para></listitem></varlistentry> 491 <varlistentry><term><sgmltag class="starttag">menuchoice</sgmltag></term><listitem><para></para></listitem></varlistentry> 492 <varlistentry><term><sgmltag class="starttag">guimenu</sgmltag></term><listitem><para></para></listitem></varlistentry> 493 <varlistentry><term><sgmltag class="starttag">guisubmenu</sgmltag></term><listitem><para></para></listitem></varlistentry> 494 <varlistentry><term><sgmltag class="starttag">guimenuitem</sgmltag></term><listitem><para></para></listitem></varlistentry> 495 <varlistentry><term><sgmltag class="starttag">guicon</sgmltag></term><listitem><para></para></listitem></varlistentry> 496 </variablelist> 392 497 </sect3> 393 498 </sect2> 394 499 <sect2 id="write_docbook_doc.usedtags.images"> 395 500 <title>Images and figures</title> 396 <para></para> 501 <para> 502 Images and figures are normally implemented like the following example. The image-file must be located in 503 <filename class="directory">doc/src/docbook/figures</filename> 504 ,otherwise the image won't be visible in the generated output files. 505 </para> 397 506 </sect2> 398 507 <sect2 id="write_docbook_doc.usedtags.examples"> 399 <title>Examples</title> 400 <para></para> 508 <title>Examples and programlisting</title> 509 <para> 510 Following describes how to insert an example and programlisting. In this 511 documentation the examples are often some kind of programlisting but they can still 512 be examples of something else. 513 </para> 514 <example id="write_docbook_doc.examples.example"> 515 <title>How to insert an example of program listing</title> 516 <programlisting> 517 <example id="<replaceable>chapterId</replaceable>.examples.<replaceable>exampleId</replaceable>"> 518 <title><replaceable>The title of the example</replaceable></title> 519 <programlisting> 520 <replaceable>The example code. Can not be indented like the source code that surrounds it 521 if the layout should have a correct look.</replaceable> 522 </programlisting> 523 </example> 524 </programlisting> 525 </example> 401 526 </sect2> 402 527 <sect2 id="write_docbook_doc.usedtags.admonitions"> … … 409 534 </term> 410 535 <listitem> 411 <para> </para>536 <para>Define a notification for the reader.</para> 412 537 </listitem> 413 538 </varlistentry> … … 417 542 </term> 418 543 <listitem> 419 <para> </para>544 <para>Define the text as a warning for the reader look up with.</para> 420 545 </listitem> 421 546 </varlistentry> … … 425 550 </term> 426 551 <listitem> 427 <para> </para>552 <para>Define something that can be useful for the reader to know.</para> 428 553 </listitem> 429 554 </varlistentry> … … 433 558 </term> 434 559 <listitem> 435 <para></para> 560 <para> 561 Define a text to be important, something the reader should pay certain 562 attention to. 563 </para> 436 564 </listitem> 437 565 </varlistentry> … … 441 569 </term> 442 570 <listitem> 443 <para></para> 571 <para> 572 Define a text about something the reader should be cautious with. 573 </para> 444 574 </listitem> 445 575 </varlistentry> … … 448 578 <sect2 id="write_docbook_doc.usedtags.lists"> 449 579 <title>Lists</title> 450 <para></para> 580 <para> 581 Following items can be used to define different kind of lists in the documentation. 582 Some common elements for the lists are also described here. 583 </para> 584 <variablelist> 585 <varlistentry> 586 <term> 587 <sgmltag class="starttag">listitem</sgmltag> 588 </term> 589 <listitem> 590 <para>Define an item in one of the three lists below.</para> 591 </listitem> 592 </varlistentry> 593 <varlistentry> 594 <term> 595 <sgmltag class="starttag">itemizedlist</sgmltag> 596 </term> 597 <listitem> 598 <para>Define a list where each item is marked with a bullet.</para> 599 </listitem> 600 </varlistentry> 601 <varlistentry> 602 <term> 603 <sgmltag class="starttag">varlist</sgmltag> 604 </term> 605 <listitem> 606 <para> 607 Define a variable list. Beside variables, this type is also being used 608 to describe different kind of items.This list type needs to have some 609 more child items to work correctly.See the 610 <ulink url="http://www.docbook.org/tdg/en/html/variablelist.html"> 611 docbook documentation 612 </ulink> 613 for more information. 614 </para> 615 </listitem> 616 </varlistentry> 617 <varlistentry> 618 <term> 619 <sgmltag class="starttag">orderedlist</sgmltag> 620 </term> 621 <listitem> 622 <para> 623 Define an ordered list with each item marked with an incremented label. 624 </para> 625 </listitem> 626 </varlistentry> 627 </variablelist> 451 628 </sect2> 452 629 </sect1>
Note: See TracChangeset
for help on using the changeset viewer.