From 01e2426b496f0eff10dbb9582f99b0cc7ca74bdf Mon Sep 17 00:00:00 2001 From: James Bursa Date: Tue, 7 Oct 2003 21:41:55 +0000 Subject: [project @ 2003-10-07 21:41:55 by bursa] Implementing a new CSS property overview. svn path=/import/netsurf/; revision=349 --- !NetSurf/Resources/CSS,f79 | 2 + Docs/Doxyfile | 297 ++++++++++++++++++++++----------------------- Docs/developer | 70 +++++++++++ 3 files changed, 216 insertions(+), 153 deletions(-) diff --git a/!NetSurf/Resources/CSS,f79 b/!NetSurf/Resources/CSS,f79 index 09a236786..96480100a 100644 --- a/!NetSurf/Resources/CSS,f79 +++ b/!NetSurf/Resources/CSS,f79 @@ -56,3 +56,5 @@ br[clear=all] { clear: both; } br[clear=left] { clear: left; } br[clear=right] { clear: right; } +td[nowrap], th[nowrap] { white-space: nowrap; } +pre { white-space: pre; } 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. + */ -- cgit v1.2.3