summaryrefslogtreecommitdiff
path: root/Docs
diff options
context:
space:
mode:
authorJames Bursa <james@netsurf-browser.org>2003-10-07 21:41:55 +0000
committerJames Bursa <james@netsurf-browser.org>2003-10-07 21:41:55 +0000
commit01e2426b496f0eff10dbb9582f99b0cc7ca74bdf (patch)
tree1196d80f81d4e56c4c1b36e30ef8ea0a9556e8c8 /Docs
parentbbcdf13fe04bc56a3671db581df40307e65b81da (diff)
downloadnetsurf-01e2426b496f0eff10dbb9582f99b0cc7ca74bdf.tar.gz
netsurf-01e2426b496f0eff10dbb9582f99b0cc7ca74bdf.tar.bz2
[project @ 2003-10-07 21:41:55 by bursa]
Implementing a new CSS property overview. svn path=/import/netsurf/; revision=349
Diffstat (limited to 'Docs')
-rw-r--r--Docs/Doxyfile297
-rw-r--r--Docs/developer70
2 files changed, 214 insertions, 153 deletions
diff --git a/Docs/Doxyfile b/Docs/Doxyfile
index c32a9926a..b28d6aae1 100644
--- a/Docs/Doxyfile
+++ b/Docs/Doxyfile
@@ -1,4 +1,4 @@
-# Doxyfile 1.3.2
+# Doxyfile 1.3.4
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project
@@ -11,7 +11,7 @@
# Values that contain spaces should be placed between quotes (" ")
#---------------------------------------------------------------------------
-# General configuration options
+# Project related configuration options
#---------------------------------------------------------------------------
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
@@ -53,6 +53,128 @@ OUTPUT_LANGUAGE = English
USE_WINDOWS_ENCODING = NO
+# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
+# include brief member descriptions after the members that are listed in
+# the file and class documentation (similar to JavaDoc).
+# Set to NO to disable this.
+
+BRIEF_MEMBER_DESC = YES
+
+# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
+# the brief description of a member or function before the detailed description.
+# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
+# brief descriptions will be completely suppressed.
+
+REPEAT_BRIEF = YES
+
+# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
+# Doxygen will generate a detailed section even if there is only a brief
+# description.
+
+ALWAYS_DETAILED_SEC = NO
+
+# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited
+# members of a class in the documentation of that class as if those members were
+# ordinary class members. Constructors, destructors and assignment operators of
+# the base classes will not be shown.
+
+INLINE_INHERITED_MEMB = NO
+
+# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
+# path before files name in the file list and in the header files. If set
+# to NO the shortest path that makes the file name unique will be used.
+
+FULL_PATH_NAMES = YES
+
+# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
+# can be used to strip a user-defined part of the path. Stripping is
+# only done if one of the specified strings matches the left-hand part of
+# the path. It is allowed to use relative paths in the argument list.
+
+STRIP_FROM_PATH = /home/james/Projects/
+
+# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
+# (but less readable) file names. This can be useful is your file systems
+# doesn't support long names like on DOS, Mac, or CD-ROM.
+
+SHORT_NAMES = NO
+
+# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
+# will interpret the first line (until the first dot) of a JavaDoc-style
+# comment as the brief description. If set to NO, the JavaDoc
+# comments will behave just like the Qt-style comments (thus requiring an
+# explict @brief command for a brief description.
+
+JAVADOC_AUTOBRIEF = YES
+
+# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
+# treat a multi-line C++ special comment block (i.e. a block of //! or ///
+# comments) as a brief description. This used to be the default behaviour.
+# The new default is to treat a multi-line C++ comment block as a detailed
+# description. Set this tag to YES if you prefer the old behaviour instead.
+
+MULTILINE_CPP_IS_BRIEF = NO
+
+# If the DETAILS_AT_TOP tag is set to YES then Doxygen
+# will output the detailed description near the top, like JavaDoc.
+# If set to NO, the detailed description appears after the member
+# documentation.
+
+DETAILS_AT_TOP = NO
+
+# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
+# member inherits the documentation from any documented member that it
+# reimplements.
+
+INHERIT_DOCS = YES
+
+# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
+# tag is set to YES, then doxygen will reuse the documentation of the first
+# member in the group (if any) for the other members of the group. By default
+# all members of a group must be documented explicitly.
+
+DISTRIBUTE_GROUP_DOC = NO
+
+# The TAB_SIZE tag can be used to set the number of spaces in a tab.
+# Doxygen uses this value to replace tabs by spaces in code fragments.
+
+TAB_SIZE = 8
+
+# This tag can be used to specify a number of aliases that acts
+# as commands in the documentation. An alias has the form "name=value".
+# For example adding "sideeffect=\par Side Effects:\n" will allow you to
+# put the command \sideeffect (or @sideeffect) in the documentation, which
+# will result in a user-defined paragraph with heading "Side Effects:".
+# You can put \n's in the value part of an alias to insert newlines.
+
+ALIASES =
+
+# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
+# only. Doxygen will then generate output that is more tailored for C.
+# For instance, some of the names that are used will be different. The list
+# of all members will be omitted, etc.
+
+OPTIMIZE_OUTPUT_FOR_C = YES
+
+# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources
+# only. Doxygen will then generate output that is more tailored for Java.
+# For instance, namespaces will be presented as packages, qualified scopes
+# will look different, etc.
+
+OPTIMIZE_OUTPUT_JAVA = NO
+
+# Set the SUBGROUPING tag to YES (the default) to allow class member groups of
+# the same type (for instance a group of public functions) to be put as a
+# subgroup of that type (e.g. under the Public Functions section). Set it to
+# NO to prevent subgrouping. Alternatively, this can be done per class using
+# the \nosubgrouping command.
+
+SUBGROUPING = YES
+
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+
# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in
# documentation are documented, even if no documentation was available.
# Private class members and static file members will be hidden unless
@@ -105,46 +227,6 @@ HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = NO
-# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
-# include brief member descriptions after the members that are listed in
-# the file and class documentation (similar to JavaDoc).
-# Set to NO to disable this.
-
-BRIEF_MEMBER_DESC = YES
-
-# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend
-# the brief description of a member or function before the detailed description.
-# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the
-# brief descriptions will be completely suppressed.
-
-REPEAT_BRIEF = YES
-
-# If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then
-# Doxygen will generate a detailed section even if there is only a brief
-# description.
-
-ALWAYS_DETAILED_SEC = NO
-
-# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited
-# members of a class in the documentation of that class as if those members were
-# ordinary class members. Constructors, destructors and assignment operators of
-# the base classes will not be shown.
-
-INLINE_INHERITED_MEMB = NO
-
-# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
-# path before files name in the file list and in the header files. If set
-# to NO the shortest path that makes the file name unique will be used.
-
-FULL_PATH_NAMES = YES
-
-# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag
-# can be used to strip a user-defined part of the path. Stripping is
-# only done if one of the specified strings matches the left-hand part of
-# the path. It is allowed to use relative paths in the argument list.
-
-STRIP_FROM_PATH = /home/james/Projects/
-
# The INTERNAL_DOCS tag determines if documentation
# that is typed after a \internal command is included. If the tag is set
# to NO (the default) then the documentation will be excluded.
@@ -160,12 +242,6 @@ INTERNAL_DOCS = NO
CASE_SENSE_NAMES = YES
-# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter
-# (but less readable) file names. This can be useful is your file systems
-# doesn't support long names like on DOS, Mac, or CD-ROM.
-
-SHORT_NAMES = NO
-
# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen
# will show members with their full class and namespace scopes in the
# documentation. If set to YES the scope will be hidden.
@@ -178,35 +254,6 @@ HIDE_SCOPE_NAMES = NO
SHOW_INCLUDE_FILES = YES
-# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen
-# will interpret the first line (until the first dot) of a JavaDoc-style
-# comment as the brief description. If set to NO, the JavaDoc
-# comments will behave just like the Qt-style comments (thus requiring an
-# explict @brief command for a brief description.
-
-JAVADOC_AUTOBRIEF = YES
-
-# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
-# treat a multi-line C++ special comment block (i.e. a block of //! or ///
-# comments) as a brief description. This used to be the default behaviour.
-# The new default is to treat a multi-line C++ comment block as a detailed
-# description. Set this tag to YES if you prefer the old behaviour instead.
-
-MULTILINE_CPP_IS_BRIEF = NO
-
-# If the DETAILS_AT_TOP tag is set to YES then Doxygen
-# will output the detailed description near the top, like JavaDoc.
-# If set to NO, the detailed description appears after the member
-# documentation.
-
-DETAILS_AT_TOP = NO
-
-# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
-# member inherits the documentation from any documented member that it
-# reimplements.
-
-INHERIT_DOCS = YES
-
# If the INLINE_INFO tag is set to YES (the default) then a tag [inline]
# is inserted in the documentation for inline members.
@@ -219,18 +266,6 @@ INLINE_INFO = YES
SORT_MEMBER_DOCS = YES
-# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
-# tag is set to YES, then doxygen will reuse the documentation of the first
-# member in the group (if any) for the other members of the group. By default
-# all members of a group must be documented explicitly.
-
-DISTRIBUTE_GROUP_DOC = NO
-
-# The TAB_SIZE tag can be used to set the number of spaces in a tab.
-# Doxygen uses this value to replace tabs by spaces in code fragments.
-
-TAB_SIZE = 8
-
# The GENERATE_TODOLIST tag can be used to enable (YES) or
# disable (NO) the todo list. This list is created by putting \todo
# commands in the documentation.
@@ -255,15 +290,6 @@ GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
-# This tag can be used to specify a number of aliases that acts
-# as commands in the documentation. An alias has the form "name=value".
-# For example adding "sideeffect=\par Side Effects:\n" will allow you to
-# put the command \sideeffect (or @sideeffect) in the documentation, which
-# will result in a user-defined paragraph with heading "Side Effects:".
-# You can put \n's in the value part of an alias to insert newlines.
-
-ALIASES =
-
# The ENABLED_SECTIONS tag can be used to enable conditional
# documentation sections, marked by \if sectionname ... \endif.
@@ -279,20 +305,6 @@ ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
-# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
-# only. Doxygen will then generate output that is more tailored for C.
-# For instance, some of the names that are used will be different. The list
-# of all members will be omitted, etc.
-
-OPTIMIZE_OUTPUT_FOR_C = YES
-
-# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources
-# only. Doxygen will then generate output that is more tailored for Java.
-# For instance, namespaces will be presented as packages, qualified scopes
-# will look different, etc.
-
-OPTIMIZE_OUTPUT_JAVA = NO
-
# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
# at the bottom of the documentation of classes and structs. If set to YES the
# list will mention the files that were used to generate the documentation.
@@ -349,16 +361,25 @@ WARN_LOGFILE =
# directories like "/usr/src/myproject". Separate the files or directories
# with spaces.
-INPUT = content css desktop render riscos utils Docs/developer
+INPUT = content \
+ css \
+ desktop \
+ render \
+ riscos \
+ utils \
+ Docs/developer
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
# and *.h) to filter out the source-files in the directories. If left
# blank the following patterns are tested:
# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp
-# *.h++ *.idl *.odl *.cs
+# *.h++ *.idl *.odl *.cs *.php *.php3 *.inc
-FILE_PATTERNS = *.c *.h *.y *.l
+FILE_PATTERNS = *.c \
+ *.h \
+ *.y \
+ *.l
# The RECURSIVE tag can be used to turn specify whether or not subdirectories
# should be searched for input files as well. Possible values are YES and NO.
@@ -370,7 +391,12 @@ RECURSIVE = NO
# excluded from the INPUT source files. This way you can easily exclude a
# subdirectory from a directory tree whose root is specified with the INPUT tag.
-EXCLUDE = css/css_enum.c css/css_enum.h css/parser.c css/parser.h css/scanner.c css/scanner.h
+EXCLUDE = css/css_enum.c \
+ css/css_enum.h \
+ css/parser.c \
+ css/parser.h \
+ css/scanner.c \
+ css/scanner.h
# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories
# that are symbolic links (a Unix filesystem feature) are excluded from the input.
@@ -863,7 +889,7 @@ INCLUDE_FILE_PATTERNS =
# or name=definition (no spaces). If the definition and the = are
# omitted =1 is assumed.
-PREDEFINED = riscos
+PREDEFINED = riscos CSS_INTERNALS
# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then
# this tag can be used to specify a list of macro names that should be expanded.
@@ -963,7 +989,7 @@ CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
# If the UML_LOOK tag is set to YES doxygen will generate inheritance and
-# colloborations diagrams in a style similiar to the OMG's Unified Modeling
+# collaboration diagrams in a style similiar to the OMG's Unified Modeling
# Language.
UML_LOOK = NO
@@ -1064,38 +1090,3 @@ DOT_CLEANUP = YES
# used. If set to NO the values of all tags below this one will be ignored.
SEARCHENGINE = NO
-
-# The CGI_NAME tag should be the name of the CGI script that
-# starts the search engine (doxysearch) with the correct parameters.
-# A script with this name will be generated by doxygen.
-
-CGI_NAME = search.cgi
-
-# The CGI_URL tag should be the absolute URL to the directory where the
-# cgi binaries are located. See the documentation of your http daemon for
-# details.
-
-CGI_URL =
-
-# The DOC_URL tag should be the absolute URL to the directory where the
-# documentation is located. If left blank the absolute path to the
-# documentation, with file:// prepended to it, will be used.
-
-DOC_URL =
-
-# The DOC_ABSPATH tag should be the absolute path to the directory where the
-# documentation is located. If left blank the directory on the local machine
-# will be used.
-
-DOC_ABSPATH =
-
-# The BIN_ABSPATH tag must point to the directory where the doxysearch binary
-# is installed.
-
-BIN_ABSPATH = /usr/local/bin/
-
-# The EXT_DOC_PATHS tag can be used to specify one or more paths to
-# documentation generated for other projects. This allows doxysearch to search
-# the documentation for these projects as well.
-
-EXT_DOC_PATHS =
diff --git a/Docs/developer b/Docs/developer
index 8acaca65a..83cd61812 100644
--- a/Docs/developer
+++ b/Docs/developer
@@ -97,4 +97,74 @@ http://netsurf.strcprstskrzkrk.co.uk/developer/
- libpng (PNG support) http://www.libpng.org/pub/png/libpng.html
- zlib http://www.gzip.org/zlib/
+\section addcss Implementing a new CSS property
+
+In this section I go through adding a CSS property to NetSurf, using the
+'white-space' property as an example. -- James Bursa
+
+1. Read and understand the description of the property in the CSS specification
+ (I have worked from CSS 2, but now 2.1 is probably better).
+
+These changes are required in the css directory:
+
+2. Add the property to css_enums. This file is used to generate css_enum.h
+ and css_enum.c:
+ \code css_white_space inherit normal nowrap pre \endcode
+ (I'm not doing pre-wrap and pre-line for now.)
+
+3. Add fields to struct ::css_style to represent the property:
+ \code css_white_space white_space; \endcode
+
+4. Add a parser function for the property to ruleset.c. Declare a new
+ function:
+ \code static void parse_white_space(struct css_style * const s, const struct css_node * const v); \endcode
+ and add it to ::property_table:
+ \code { "white-space", parse_white_space }, \endcode
+ This will cause the function to be called when the parser comes to a rule
+ giving a value for white-space. The function is passed a linked list of
+ struct ::css_node, each of which corresponds to a token in the CSS source,
+ and must update s to correspond to that rule. For white-space, the
+ implementation is simply:
+\code
+void parse_white_space(struct css_style * const s, const struct css_node * const v)
+{
+ css_white_space z;
+ if (v->type != CSS_NODE_IDENT || v->next != 0)
+ return;
+ z = css_white_space_parse(v->data);
+ if (z != CSS_WHITE_SPACE_UNKNOWN)
+ s->white_space = z;
+}
+\endcode
+ First we check that the value consists of exactly one identifier, as
+ described in the specification. If it is not, we ignore it, since it may be
+ some future CSS. The css_white_space_parse() function is generated in
+ css_enum.c, and converts a string giving a value to a constant. If the
+ conversion succeeds, the style s is updated.
+
+5. Add defaults for the style to ::css_base_style, ::css_empty_style, and
+ ::css_blank_style in css.c. The value in css_base_style should be the one
+ given as 'Initial' in the spec, and the value in css_empty_style should be
+ inherit. If 'Inherited' is yes in the spec, the value in css_blank_style
+ should be inherit, otherwise it should be the one given as 'Initial'. Thus
+ for white-space, which has "Initial: normal, Inherited: yes" in the spec, we
+ use CSS_WHITE_SPACE_NORMAL in css_base_style and CSS_WHITE_SPACE_INHERIT in
+ the other two.
+
+6. Edit css_cascade() and css_merge() in css.c to handle the property. In
+ both cases for white-space this looks like:
+ \code
+ if (apply->white_space != CSS_WHITE_SPACE_INHERIT)
+ style->white_space = apply->white_space;
+ \endcode
+ Add the property to css_dump_style() (not essential).
+
+Now the box, layout and / or redraw code needs to be changed to use the new
+style property. This varies much more depending on the property.
+
+For white-space, convert_xml_to_box() was changed to split text at newlines if
+white-space was pre, and to replace spaces with hard spaces for nowrap.
+Additionally, calculate_inline_container_widths() was changed to give the
+appropriate minimum width for pre and nowrap.
+
*/