GNOME.org
 

[gtksourceview] More work on inlining docs and split the stylescheme reference in a standalone file

commit 1d9a4995bc90d8ab0e48e08fd37652a43f201877
Author: Paolo Borelli <pborelli gnome org>
Date:   Sun Dec 27 19:05:00 2009 +0100

    More work on inlining docs and split the stylescheme reference in a
    standalone file

 docs/reference/Makefile.am                         |    3 +-
 docs/reference/gtksourceview-docs.sgml             |    2 +
 .../stylescheme.sgml => style-reference.sgml}      |  127 ++++----------------
 docs/reference/tmpl/language.sgml                  |  132 --------------------
 docs/reference/tmpl/languagemanager.sgml           |  105 ----------------
 docs/reference/tmpl/style.sgml                     |  105 ----------------
 docs/reference/tmpl/styleschememanager.sgml        |  114 -----------------
 gtksourceview/gtksourcelanguage.c                  |   16 ++-
 gtksourceview/gtksourcelanguagemanager.c           |   19 +++-
 gtksourceview/gtksourcemark.c                      |    6 +-
 gtksourceview/gtksourceprintcompositor.c           |   23 +++-
 gtksourceview/gtksourcestyle.c                     |    9 ++
 gtksourceview/gtksourcestylescheme.c               |   20 +++-
 gtksourceview/gtksourcestyleschememanager.c        |   12 ++-
 14 files changed, 117 insertions(+), 576 deletions(-)
---
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index b7f52de..0464835 100644
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -59,7 +59,8 @@ HTML_IMAGES =
 content_files =			\
 	version.xml		\
 	lang-tutorial.sgml	\
-	lang-reference.sgml
+	lang-reference.sgml	\
+	style-reference.sgml
 
 # Extra options to supply to gtkdoc-fixref
 FIXXREF_OPTIONS=
diff --git a/docs/reference/gtksourceview-docs.sgml b/docs/reference/gtksourceview-docs.sgml
index d19903f..1845770 100644
--- a/docs/reference/gtksourceview-docs.sgml
+++ b/docs/reference/gtksourceview-docs.sgml
@@ -4,6 +4,7 @@
 <!ENTITY version SYSTEM "version.xml">
 <!ENTITY tutorial SYSTEM "lang-tutorial.sgml">
 <!ENTITY reference SYSTEM "lang-reference.sgml">
+<!ENTITY stylereference SYSTEM "style-reference.sgml">
 ]>
 <book id="index" xmlns:xi="http://www.w3.org/2001/XInclude";>
   <bookinfo>
@@ -37,5 +38,6 @@
 
     &tutorial;
     &reference;
+    &stylereference;
   </reference>
 </book>
diff --git a/docs/reference/tmpl/stylescheme.sgml b/docs/reference/style-reference.sgml
similarity index 76%
rename from docs/reference/tmpl/stylescheme.sgml
rename to docs/reference/style-reference.sgml
index a0ad55c..6f4b456 100644
--- a/docs/reference/tmpl/stylescheme.sgml
+++ b/docs/reference/style-reference.sgml
@@ -1,22 +1,28 @@
-<!-- ##### SECTION Title ##### -->
-GtkSourceStyleScheme
+<refentry id="style-reference" revision="27 December 2009">
+<refmeta>
+<refentrytitle>Style Scheme Definition Reference</refentrytitle>
+</refmeta>
 
-<!-- ##### SECTION Short_Description ##### -->
+<refnamediv>
+<refname>Style Scheme Definition Reference</refname>
+<refpurpose>
+Reference to the GtkSourceView style scheme definition file format
+</refpurpose>
+</refnamediv>
 
-Object controlling apperance of #GtkSourceView
-
-<!-- ##### SECTION Long_Description ##### -->
+<refsect1>
+<title>Overview</title>
 <para>
-#GtkSourceStyleScheme contains all the text styles to be used
-in #GtkSourceView and #GtkSourceBuffer. For instance, it contains
-text styles for syntax highlighting, it may contain foreground
-and background color for non-highlighted text, etc.
+This is an overview of the Style Scheme Definition XML format, describing the
+meaning and usage of every element and attribute.  The formal definition is
+stored in the RelaxNG schema file <filename>style.rng</filename> which
+should be installed on your system in the directory
+<filename>${PREFIX}/share/gtksourceview-2.0/</filename> (where
+<filename>${PREFIX}</filename> can be <filename>/usr/</filename> or
+<filename>/usr/local/</filename> if you have installed from source.
 </para>
+</refsect1>
 
-<para>
-Style schemes are stored in XML files. The format of scheme file is
-the following.
-</para>
 
 <para>
 The toplevel tag in a style scheme file is <code>&lt;style-scheme&gt;</code>.
@@ -191,94 +197,5 @@ drawn</para></listitem>
 </varlistentry>
 </variablelist>
 </para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GtkSourceStyle, #GtkSourceStyleSchemeManager
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### STRUCT GtkSourceStyleScheme ##### -->
-<para>
-<structname>GtkSourceStyleScheme</structname> structure contains only
-private members and should not be accessed directly.
-</para>
-
-
-<!-- ##### ARG GtkSourceStyleScheme:description ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSourceStyleScheme:filename ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSourceStyleScheme:id ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GtkSourceStyleScheme:name ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_source_style_scheme_get_id ##### -->
-<para>
-
-</para>
-
- scheme: 
- Returns: 
-
-
-<!-- ##### FUNCTION gtk_source_style_scheme_get_name ##### -->
-<para>
-
-</para>
-
- scheme: 
- Returns: 
-
-
-<!-- ##### FUNCTION gtk_source_style_scheme_get_description ##### -->
-<para>
-
-</para>
-
- scheme: 
- Returns: 
-
-
-<!-- ##### FUNCTION gtk_source_style_scheme_get_authors ##### -->
-<para>
-
-</para>
-
- scheme: 
- Returns: 
-
-
-<!-- ##### FUNCTION gtk_source_style_scheme_get_filename ##### -->
-<para>
-
-</para>
-
- scheme: 
- Returns: 
-
-
-<!-- ##### FUNCTION gtk_source_style_scheme_get_style ##### -->
-<para>
-
-</para>
-
- scheme: 
- style_id: 
- Returns: 
-
-
+ 
+</refentry>
diff --git a/gtksourceview/gtksourcelanguage.c b/gtksourceview/gtksourcelanguage.c
index 09f123a..87038ad 100644
--- a/gtksourceview/gtksourcelanguage.c
+++ b/gtksourceview/gtksourcelanguage.c
@@ -1,5 +1,5 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*-
- *  gtksourcelanguage.c
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
+/*  gtksourcelanguage.c
  *
  *  Copyright (C) 2003 - Paolo Maggi <paolo maggi polito it>
  *
@@ -39,6 +39,18 @@
 #include "gtksourcelanguage.h"
 #include "gtksourceview-marshal.h"
 
+/**
+ * SECTION:language
+ * @Short_description: Object representing a syntax highlighted language
+ * @Title: GtkSourceLanguage
+ * @See_also: #GtkSourceLanguageManager
+ *
+ * #GtkSourceLanguage encapsulates syntax and highlighting styles for a
+ * particular language. Use #GtkSourceLanguageManager to obtain a
+ * #GtkSourceLanguage instance, and gtk_source_buffer_set_language() to apply it
+ * to a #GtkSourceBuffer.
+ */
+
 #define DEFAULT_SECTION _("Others")
 
 /* Properties */
diff --git a/gtksourceview/gtksourcelanguagemanager.c b/gtksourceview/gtksourcelanguagemanager.c
index f4e3ddb..ac6466a 100644
--- a/gtksourceview/gtksourcelanguagemanager.c
+++ b/gtksourceview/gtksourcelanguagemanager.c
@@ -1,5 +1,5 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*-
- *  gtksourcelanguagemanager.c
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
+/*  gtksourcelanguagemanager.c
  *
  *  Copyright (C) 2003-2007 - Paolo Maggi <paolo maggi polito it>
  *
@@ -29,6 +29,21 @@
 #include "gtksourceview-utils.h"
 #include <gio/gio.h>
 
+/**
+ * SECTION:languagemanager
+ * @Short_description: Object which provides access to #GtkSourceLanguage<!-- -->s
+ * @Title: GtkSourceLanguageManager
+ * @See_also: #GtkSourceLanguage
+ *
+ * #GtkSourceLanguageManager is an object which processes language description
+ * files and creates and stores #GtkSourceLanguage objects, and provides API to
+ * access them.
+ * Use gtk_source_language_manager_get_default() to retrieve the default
+ * instance of #GtkSourceLanguageManager, and
+ * gtk_source_language_manager_guess_language() to get a #GtkSourceLanguage for
+ * given file name and content type.
+ */
+
 #define RNG_SCHEMA_FILE		"language2.rng"
 #define LANGUAGE_DIR		"language-specs"
 #define LANG_FILE_SUFFIX	".lang"
diff --git a/gtksourceview/gtksourcemark.c b/gtksourceview/gtksourcemark.c
index 9230fd0..6c6d29c 100644
--- a/gtksourceview/gtksourcemark.c
+++ b/gtksourceview/gtksourcemark.c
@@ -33,9 +33,9 @@
  * additional info. It is based on #GtkTextMark and thus is still valid after
  * the text has changed though its position may change.
  *
- * #GtkSourceMarks are organised in categories which you have to set when you
- * create the mark. Each category can have a pixbuf and a priority associated
- * using #gtk_source_view_set_mark_category_pixbuf and
+ * #GtkSourceMark<!-- -->s are organised in categories which you have to set
+ * when you create the mark. Each category can have a pixbuf and a priority
+ * associated using #gtk_source_view_set_mark_category_pixbuf and
  * #gtk_source_view_set_mark_category_priority. The pixbuf will be displayed in
  * the margin at the line where the mark residents if the
  * #GtkSourceView::show-line-marks property is set to TRUE. If there are
diff --git a/gtksourceview/gtksourceprintcompositor.c b/gtksourceview/gtksourceprintcompositor.c
index 489a812..cdcc2f4 100644
--- a/gtksourceview/gtksourceprintcompositor.c
+++ b/gtksourceview/gtksourceprintcompositor.c
@@ -1,5 +1,5 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*-
- *
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
+/*
  * gtksourceprintcompositor.c
  * This file is part of GtkSourceView 
  *
@@ -34,6 +34,25 @@
 #include "gtksourceview-i18n.h" 
 #include "gtksourceprintcompositor.h"
 
+/**
+ * SECTION:printcompositor
+ * @Short_description: Compose a #GtkSourceBuffer for printing
+ * @Title: GtkSourcePrintCompositor
+ *
+ * The #GtkSourcePrintCompositor object is used to compose a #GtkSourceBuffer
+ * for printing. You can set various configuration options to customize the
+ * printed output. #GtkSourcePrintCompositor is designed to be used with the
+ * high-level printing API of gtk+, i.e. #GtkPrintOperation.
+ *
+ * The margins specified in this object are the layout margins: they define the
+ * blank space bordering the printed area of the pages. They must not be
+ * confused with the "print margins", i.e. the parts of the page that the
+ * printer cannot print on, defined in the #GtkPageSetup objects. If the
+ * specified layout margins are smaller than the "print margins", the latter
+ * ones are used as a fallback by the #GtkSourcePrintCompositor object, so that
+ * the printed area is not clipped.
+ */
+
 /*
 #define ENABLE_DEBUG
 #define ENABLE_PROFILE
diff --git a/gtksourceview/gtksourcestyle.c b/gtksourceview/gtksourcestyle.c
index 7941cd4..f89fd1c 100644
--- a/gtksourceview/gtksourcestyle.c
+++ b/gtksourceview/gtksourcestyle.c
@@ -21,6 +21,15 @@
 #include "gtksourcestyle-private.h"
 #include "gtksourceview-i18n.h"
 
+/**
+ * SECTION:style
+ * @Short_description: Object representyng a style
+ * @Title: GtkSourceStyle
+ * @See_also: #GtkSourceStyleScheme, #GtkSourceStyleSchemeManager
+ *
+ * The #GtkSourceStyle structure is used to describe text attributes
+ * which are set when given style is used.
+ */
 
 static void	gtk_source_style_set_property	(GObject      *object,
 						 guint         prop_id,
diff --git a/gtksourceview/gtksourcestylescheme.c b/gtksourceview/gtksourcestylescheme.c
index 8a5c7d7..02c0251 100644
--- a/gtksourceview/gtksourcestylescheme.c
+++ b/gtksourceview/gtksourcestylescheme.c
@@ -1,5 +1,5 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*-
- *  gtksourcestylescheme.c
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
+/*  gtksourcestylescheme.c
  *
  *  Copyright (C) 2003 - Paolo Maggi <paolo maggi polito it>
  *
@@ -26,6 +26,22 @@
 #include <libxml/parser.h>
 #include <string.h>
 
+/**
+ * SECTION:stylescheme
+ * @Short_description: Object controlling apperance of #GtkSourceView
+ * @Title: GtkSourceStyleScheme
+ * @See_also: #GtkSourceStyle, #GtkSourceStyleSchemeManager
+ *
+ * #GtkSourceStyleScheme contains all the text styles to be used in
+ * #GtkSourceView and #GtkSourceBuffer. For instance, it contains text styles
+ * for syntax highlighting, it may contain foreground and background color for
+ * non-highlighted text, color for the line numbers, etc.
+ *
+ * Style schemes are stored in XML files. The format of a scheme file is
+ * the documented in the 
+ * <link linkend="style-reference">style scheme reference</link>.
+ */
+
 #define STYLE_TEXT			"text"
 #define STYLE_SELECTED			"selection"
 #define STYLE_SELECTED_UNFOCUSED	"selection-unfocused"
diff --git a/gtksourceview/gtksourcestyleschememanager.c b/gtksourceview/gtksourcestyleschememanager.c
index 416bdde..aff21bf 100644
--- a/gtksourceview/gtksourcestyleschememanager.c
+++ b/gtksourceview/gtksourcestyleschememanager.c
@@ -1,5 +1,5 @@
-/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*-
- *  gtksourcestyleschememanager.c
+/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8; coding: utf-8 -*- */
+/*  gtksourcestyleschememanager.c
  *
  *  Copyright (C) 2003-2007 - Paolo Maggi <paolo gnome org>
  *
@@ -24,10 +24,16 @@
 #include "gtksourceview-utils.h"
 #include <string.h>
 
+/**
+ * SECTION:styleschememanager
+ * @Short_description: Object which provides access to #GtkSourceStyleScheme<!-- -->s
+ * @Title: GtkSourceStyleSchemeManager
+ * @See_also: #GtkSourceStyleScheme
+ */
+
 #define SCHEME_FILE_SUFFIX	".xml"
 #define STYLES_DIR		"styles"
 
-
 struct _GtkSourceStyleSchemeManagerPrivate
 {
 	GHashTable	*schemes_hash;
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]