forked from enlightenment/efl
parent
7aa1a10080
commit
c19e148c3e
|
@ -0,0 +1,46 @@
|
||||||
|
## Process this file with automake to produce Makefile.in
|
||||||
|
|
||||||
|
MAINTAINERCLEANFILES = Makefile.in
|
||||||
|
|
||||||
|
EXTRA_DIST = \
|
||||||
|
manual.raw \
|
||||||
|
kernel-doc.in \
|
||||||
|
stylesheet.css \
|
||||||
|
figures/*.gif # Add any images you create here
|
||||||
|
|
||||||
|
|
||||||
|
## Fill in all source files that you documented
|
||||||
|
## with extractable comments here:
|
||||||
|
##
|
||||||
|
SOURCEDOC = $(top_srcdir)/src/Ecore.h
|
||||||
|
|
||||||
|
## For details on what can be specified in the
|
||||||
|
## comments, see the beginning of kernel-doc
|
||||||
|
## in this directory! -- cK.
|
||||||
|
|
||||||
|
|
||||||
|
SGMLFILE = $(PACKAGE)-manual.sgml
|
||||||
|
|
||||||
|
docs: manual.raw $(SOURCEDOC)
|
||||||
|
./kernel-doc -docbook <manual.raw >$(SGMLFILE)
|
||||||
|
|
||||||
|
if HAVE_JADE
|
||||||
|
|
||||||
|
FULLNAME = $(PACKAGE)-manual-$(VERSION)
|
||||||
|
|
||||||
|
html-docs: docs html-customizations.dsl
|
||||||
|
$(mkinstalldirs) ./$(FULLNAME)/figures
|
||||||
|
cd $(FULLNAME) && @JADE@ -t sgml -d ../html-customizations.dsl ../$(SGMLFILE)
|
||||||
|
- cd figures && cp -f *.gif ../$(FULLNAME)/figures
|
||||||
|
- cd figures && cp -f *.png ../$(FULLNAME)/figures
|
||||||
|
- cd figures && cp -f *.jpg ../$(FULLNAME)/figures
|
||||||
|
cp -f stylesheet.css $(FULLNAME)/stylesheet.css
|
||||||
|
tar cfvz $(FULLNAME).tar.gz $(FULLNAME)
|
||||||
|
|
||||||
|
html-filetypes: filetypes.xsl
|
||||||
|
$(mkinstalldirs) ./$(FULLNAME)/filetypes
|
||||||
|
cp -fr filetypes-templates/* ./$(FULLNAME)/filetypes
|
||||||
|
./generate-trees.sh ./$(FULLNAME)/filetypes
|
||||||
|
|
||||||
|
endif
|
||||||
|
|
Binary file not shown.
After Width: | Height: | Size: 6.3 KiB |
Binary file not shown.
After Width: | Height: | Size: 1.0 KiB |
Binary file not shown.
After Width: | Height: | Size: 1.0 KiB |
Binary file not shown.
After Width: | Height: | Size: 1.0 KiB |
|
@ -0,0 +1,61 @@
|
||||||
|
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
|
||||||
|
<!ENTITY dbstyle SYSTEM "@DB_STYLESHEETS@/html/docbook.dsl" CDATA DSSSL>
|
||||||
|
]>
|
||||||
|
|
||||||
|
<style-sheet>
|
||||||
|
<style-specification use="docbook">
|
||||||
|
<style-specification-body>
|
||||||
|
|
||||||
|
;; my own customizations for HTML output:
|
||||||
|
|
||||||
|
(define %admon-graphics-path%
|
||||||
|
;; Path to admonition graphics
|
||||||
|
"figures/")
|
||||||
|
|
||||||
|
(define %admon-graphics%
|
||||||
|
;; Use graphics in admonitions?
|
||||||
|
#t)
|
||||||
|
|
||||||
|
(define %indent-programlisting-lines%
|
||||||
|
;; Indent lines in a 'ProgramListing'?
|
||||||
|
" ")
|
||||||
|
|
||||||
|
(define %shade-verbatim%
|
||||||
|
;; Should verbatim environments be shaded?
|
||||||
|
#t)
|
||||||
|
|
||||||
|
(define ($shade-verbatim-attr$)
|
||||||
|
;; Attributes used to create a shaded verbatim environment.
|
||||||
|
(list
|
||||||
|
(list "BORDER" "0")
|
||||||
|
(list "BGCOLOR" "#f0f0f0")))
|
||||||
|
|
||||||
|
(define %root-filename%
|
||||||
|
;; Name for the root HTML document
|
||||||
|
"index")
|
||||||
|
|
||||||
|
(define %body-attr%
|
||||||
|
;; What attributes should be hung off of BODY?
|
||||||
|
(list
|
||||||
|
(list "BGCOLOR" "#FFFFFF")
|
||||||
|
(list "TEXT" "#0000A0")
|
||||||
|
(list "LINK" "#2020D0")
|
||||||
|
(list "VLINK" "#000060")
|
||||||
|
(list "ALINK" "#5050F0")))
|
||||||
|
|
||||||
|
(define %css-decoration%
|
||||||
|
;; Enable CSS decoration of elements
|
||||||
|
#t)
|
||||||
|
|
||||||
|
(define %stylesheet%
|
||||||
|
;; Name of the stylesheet to use
|
||||||
|
"stylesheet.css")
|
||||||
|
|
||||||
|
(define biblio-number
|
||||||
|
;; Enumerate bibliography entries
|
||||||
|
#t)
|
||||||
|
|
||||||
|
</style-specification-body>
|
||||||
|
</style-specification>
|
||||||
|
<external-specification id="docbook" document="dbstyle">
|
||||||
|
</style-sheet>
|
File diff suppressed because it is too large
Load Diff
|
@ -0,0 +1,283 @@
|
||||||
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
|
||||||
|
<!ENTITY efsd "<function>efsd</function>">
|
||||||
|
]>
|
||||||
|
|
||||||
|
|
||||||
|
<book id="efsd-documentation-howto">
|
||||||
|
<bookinfo>
|
||||||
|
<title>EFSD Documentation Howto</title>
|
||||||
|
|
||||||
|
<authorgroup>
|
||||||
|
<author>
|
||||||
|
<firstname>FIRSTNAME</firstname>
|
||||||
|
<othername>OTHER</othername>
|
||||||
|
<surname>LASTNAME</surname>
|
||||||
|
<affiliation>
|
||||||
|
<address>
|
||||||
|
<email>EMAIL</email>
|
||||||
|
</address>
|
||||||
|
</affiliation>
|
||||||
|
</author>
|
||||||
|
</authorgroup>
|
||||||
|
|
||||||
|
<copyright>
|
||||||
|
<year>2001</year>
|
||||||
|
<holder>Christian Kreibich</holder>
|
||||||
|
</copyright>
|
||||||
|
|
||||||
|
<legalnotice>
|
||||||
|
<para>
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to
|
||||||
|
deal in the Software without restriction, including without limitation the
|
||||||
|
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
|
||||||
|
sell copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
The above copyright notice and this permission notice shall be included in
|
||||||
|
all copies of the Software and its documentation and acknowledgment shall be
|
||||||
|
given in the documentation and software packages that this Software was
|
||||||
|
used.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
|
||||||
|
THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
||||||
|
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
||||||
|
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||||
|
</para>
|
||||||
|
</legalnotice>
|
||||||
|
|
||||||
|
<releaseinfo>
|
||||||
|
This is document is nowhere near being finished. Be patient.
|
||||||
|
</releaseinfo>
|
||||||
|
|
||||||
|
</bookinfo>
|
||||||
|
|
||||||
|
<toc></toc>
|
||||||
|
|
||||||
|
<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.
|
||||||
|
</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>
|
||||||
|
<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>
|
||||||
|
</para>
|
||||||
|
</chapter>
|
||||||
|
|
||||||
|
<chapter id="samples">
|
||||||
|
<title id="samples.title">DocBook Examples</title>
|
||||||
|
<section>
|
||||||
|
<title>Lists</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>
|
||||||
|
<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>
|
||||||
|
|
||||||
|
</para>
|
||||||
|
</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>
|
||||||
|
</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>
|
||||||
|
|
|
@ -0,0 +1,20 @@
|
||||||
|
body { margin-left:10px;
|
||||||
|
margin-right:10px;
|
||||||
|
margin-top:10px;
|
||||||
|
margin-bottom:10px;
|
||||||
|
color:#0000a0;
|
||||||
|
font-size:12pt;
|
||||||
|
background-image:url(figures/background.gif);
|
||||||
|
background-repeat:no-repeat;
|
||||||
|
}
|
||||||
|
|
||||||
|
th {
|
||||||
|
font-size:14pt;
|
||||||
|
}
|
||||||
|
|
||||||
|
td {
|
||||||
|
font-size:12pt;
|
||||||
|
}
|
||||||
|
|
||||||
|
div.mediaobject { align:center; }
|
||||||
|
div.caption { align:center; }
|
Loading…
Reference in New Issue