diff options
author | cpk <cpk> | 2001-10-21 22:03:36 +0000 |
---|---|---|
committer | cpk <cpk@7cbeb6ba-43b4-40fd-8cce-4c39aea84d33> | 2001-10-21 22:03:36 +0000 |
commit | 79ef2ccbe9e8e32e350bc7e822efcb7d5671a57b (patch) | |
tree | 483a273b483fd7a419eceb6c67517ba8c654d56e /doc | |
parent | 1a24c75a7628b6b1b2e0c2458a26adc728d77395 (diff) | |
download | enlightenment-79ef2ccbe9e8e32e350bc7e822efcb7d5671a57b.tar.gz enlightenment-79ef2ccbe9e8e32e350bc7e822efcb7d5671a57b.tar.xz enlightenment-79ef2ccbe9e8e32e350bc7e822efcb7d5671a57b.zip |
Created a documentation skeleton and changed the comments in iconbar.c
so that they're useful for the documentation system.
SVN revision: 5547
Diffstat (limited to 'doc')
-rw-r--r-- | doc/manual.raw | 263 |
1 files changed, 56 insertions, 207 deletions
diff --git a/doc/manual.raw b/doc/manual.raw index 65d9325a2..a711f2304 100644 --- a/doc/manual.raw +++ b/doc/manual.raw @@ -1,20 +1,19 @@ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ -<!ENTITY efsd "<function>efsd</function>"> +<!ENTITY e17 "<productname>Enlightenment 0.17</productname>"> ]> <book id="efsd-documentation-howto"> <bookinfo> - <title>Enlightenment Documentation Howto</title> + <title>The Enlightenment 0.17 Manual</title> <authorgroup> <author> - <firstname>FIRSTNAME</firstname> - <othername>OTHER</othername> - <surname>LASTNAME</surname> + <firstname>Christian</firstname> + <surname>Kreibich</surname> <affiliation> <address> - <email>EMAIL</email> + <email>cK@whoop.org</email> </address> </affiliation> </author> @@ -61,223 +60,73 @@ <chapter id="introduction"> <title>Introduction</title> <para> - This is some sample documentation for you project. You'll need to be - familiar with <ulink url="http://docbook.org">DocBook</ulink> - to make best use of Enlightenment's documentation scheme. + This document explains the &e17; release, for both users and + developers. </para> - <para> - See <link linkend="files" endterm="files.title"></link> - for an explanation of the documentation setup in you project. - </para> - <para> - <link linkend="comments" endterm="comments.title"></link> explains - the way you have to structure your comments so that they can be - extracted. - </para> - <para> - <link linkend="samples" endterm="samples.title"></link> contains a few - layout and markup examples to get you up to speed quickly. - </para> - </chapter> - - <chapter id="files"> - <title id="files.title">Documentation File Structure</title> - <para> - The entire documentation setup lives in the <filename>doc</filename> - directory. The file you need to edit is called <filename>manual.raw</filename>. - When you enter <command>make docs</command> in the toplevel directory, - it gets translated into a standard SGML file using a Perl script. - The script scans the file for any lines starting directly with the - string <command>!I<filename></command>. Here, - <filename>filename</filename> is the name of a code - file in which you have put extractable comments. The Perl script will - then analyze the file and generate SGML DocBook statements for those - comments right into the output file. - </para> - <para> - The resulting file of that step is called <filename>$PACKAGE-manual-$VERSION.sgml</filename> - where PACKAGE and VERSION are automatically set during the build process. - This sgml file can be postprocessed with any SGML processor to generate - for example HTML, TeX or PDF output. - </para> - <para> - Suppport for HTML generation is included already through the - <command>make html-docs</command> target. In order to be able to use - that, you'll need to have <command>jade</command> installed, and appropriate - DocBook stylesheets. If the <command>configure</command> script doesn't automatically find - you stylesheets (on a Debian system it should), you can specify them when - calling <command>configure</command> or <command>autogen.sh</command> using - the <command>--with-dbsheets=DIR</command> option. - </para> - <para> - If everything worked out fine, you'll get a tarball of the HTML version - of your documentation and the extracted version in the docs directory, - named similarly to the SGML file. - </para> - </chapter> - <chapter id="comments"> - <title id="comments.title">Writing Extractable Comments</title> + <chapter id="using"> + <title>Using &e17;</title> <para> - I'll simply give an example of a commented function here: - - <programlisting> - -/** - * efsd_wait_event - blocking wait for next Efsd event. - * @ec: The Efsd connection - * @ev: Pointer to an allocated EfsdEvent. - * - * Blocks until an efsd event arrives, then returns it by filling - * in the @ev structure. Returns -1 when there was an error, - * >= 0 otherwise. - */ -int efsd_wait_event(EfsdConnection *ec, EfsdEvent *ev); - </programlisting> - As you can see, it's not hard -- just use two asterisks - to signal the start of an extractable comment. In the first - line, begin with the function name and a one-liner description. - Then, put each parameter in the following lines. Add an empty - line, and then a more verbose description. That's basically - it, you can also markup items differently as follows: - - <itemizedlist mark="opencircle"> - <listitem> - <para><command>funcname()</command> for function names</para> - </listitem> - <listitem> - <para><command>$ENVVAR</command> for environment variables</para> - </listitem> - <listitem> - <para><command>&struct_name</command> for structures</para> - </listitem> - <listitem> - <para><command>%CONST</command> for constants/para> - </listitem> - </itemizedlist> + Here's how you use &e17;. </para> - </chapter> - <chapter id="samples"> - <title id="samples.title">DocBook Examples</title> - <section> - <title>Lists</title> + <section id="wm"> + <title id="wm.title">The Window Manager</title> <para> - <itemizedlist mark="opencircle"> - <listitem> - <para>This</para> - </listitem> - <listitem> - <para>is</para> - </listitem> - <listitem> - <para>a</para> - </listitem> - <listitem> - <para>list</para> - </listitem> - </itemizedlist> </para> </section> - <section> - <title>Code</title> + + <section id="fm"> + <title id="fm.title">The File Manager</title> <para> - <programlisting> - -EfsdConnection *ec; - -if ( (ec = efsd_open()) == NULL) - { - /* Oops. Couldn't establish connection. - * Is Efsd really running ? - */ - } - -/* ... various efsd commands ... */ - -if (efsd_close(ec) < 0) - { - /* Ouch. Error when closing connection. */ - } - </programlisting> </para> </section> - <section> - <title>Images</title> - <para> - - <mediaobject> - <imageobject> - <imagedata fileref="figures/sampleimage.eps" format="eps"> - </imageobject> - <imageobject> - <imagedata fileref="figures/sampleimage.gif" format="gif"> - </imageobject> - <textobject> - <phrase>Sample image</phrase> - </textobject> - <caption> - <para>This is how you display images.</para> - </caption> - </mediaobject> + </chapter> - </para> + <chapter id="inside"> + <title>Inside &e17;</title> + <para> + This chapter explains the inner workings of &e17;. + </para> + <section id="architecture"> + <title id="architecture.title">&e17; Architecture</title> + <section id="overall"> + <title id="overall.title">Overview</title> + <para> + </para> + </section> + <section id="modules"> + <title id="modules.title">Modules</title> + <para> + </para> + </section> </section> - <section> - <title>Warnings, Notes</title> - <para> - <note> - <title>This is an example of a note.</title> - <para> - It's really simple to use. - </para> - </note - </para> - <para> - <caution> - <title>This is a warning.</title> - <para> - It's used just like a note. - </para> - </caution> - </para> + + <section id="concepts"> + <title id="concepts.title">Themeing</title> + <section id="overview"> + <title id="overview.title">Overview</title> + <para> + </para> + </section> + <section id="system"> + <title id="system.title">System Settings</title> + <para> + </para> + </section> + <section id="user"> + <title id="user.title">User Settings</title> + <para> + </para> + </section> + </section> + + <section id="code"> + <title>Code Documentation</title> +!Isrc/iconbar.c </section> </chapter> - <bibliography> - - <biblioentry id="bib-unp"> - <bookbiblio> - <author> - <firstname>W. R.</firstname> - <surname>Stevens</surname> - </author> - <title>UNIX Network Programming</title> - <edition>Second Edition</edition> - <volumenum>Volume 1</volumenum> - <publisher> - <publishername>Prentice-Hall</publishername> - </publisher> - <date>1998</date> - </bookbiblio> - </biblioentry> - - <biblioentry id="bib-apue"> - <bookbiblio> - <author> - <firstname>W. R.</firstname> - <surname>Stevens</surname> - </author> - <title>Advanced Programming in the UNIX Environment</title> - <publisher> - <publishername>Addison-Wesley</publishername> - </publisher> - <date>1992</date> - </bookbiblio> - </biblioentry> - - </bibliography> - </book> |