Author: mordante
Date: Sat Feb 26 09:54:02 2011
New Revision: 48646
URL: http://svn.gna.org/viewcvs/wesnoth?rev=48646&view=rev
Log:
Improve linking to references.
Use cleveref and add some helper macros for references it can't handle
(yet). Support for listings is in a newer version, so look at that in
the future.
Modified:
trunk/doc/design/gui2.sty
trunk/doc/design/gui2/creating_widgets_and_dialogs.tex
trunk/doc/design/gui2/design_details.tex
trunk/doc/design/gui2/files_for_the_widget.tex
trunk/doc/design/gui2/files_for_the_window.tex
Modified: trunk/doc/design/gui2.sty
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/doc/design/gui2.sty?rev=48646&r1=48645&r2=48646&view=diff
==============================================================================
--- trunk/doc/design/gui2.sty (original)
+++ trunk/doc/design/gui2.sty Sat Feb 26 09:54:02 2011
@@ -1,4 +1,4 @@
-\usepackage{listings}
+\RequirePackage{listings}
\lstset{
basicstyle=\footnotesize
, numbers = left
@@ -18,3 +18,26 @@
language = WML
, escapeinside = {/*@}{@*/}}
+%
+% Cleveref
+%
+\RequirePackage{cleveref}
+% \crefalias{lstnumber}{line}%
+% \crefalias{lstlisting}{listing}%
+\newcommand{\equationname}{Equation}
+
+% Set default formats, the uppercase format also sets the lowercase format.
+\Crefformat{appendix}{\appendixname~#2#1#3}
+\Crefformat{chapter}{\chaptername~#2#1#3}
+\Crefformat{equation}{\equationname\relax~#2#1#3}
+\Crefformat{figure}{\figurename\relax~#2#1#3}
+\Crefformat{section}{\S#2#1#3}
+\Crefformat{table}{\tablename~#2#1#3}
+\Crefformat{lstlisting}{\lstlistingname~#2#1#3}
+
+\newcommand{\Liref}[1]{Listing \ref{#1}}
+
+\newcommand{\Lref}[1]{Line \ref{#1}}
+\newcommand{\lref}[1]{line \ref{#1}}
+
+
Modified: trunk/doc/design/gui2/creating_widgets_and_dialogs.tex
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/doc/design/gui2/creating_widgets_and_dialogs.tex?rev=48646&r1=48645&r2=48646&view=diff
==============================================================================
--- trunk/doc/design/gui2/creating_widgets_and_dialogs.tex (original)
+++ trunk/doc/design/gui2/creating_widgets_and_dialogs.tex Sat Feb 26 09:54:02
2011
@@ -33,14 +33,14 @@
a certain definition of a progress bar.
\begin{description}
-\item[hpp] Listing \ref{widget_definition.hpp} contains the sample code.
- \begin{description}
- \item[Line \ref{widget_definition.hpp:control}] Normally a
+\item[hpp] \Liref{widget_definition.hpp} contains the sample code.
+ \begin{description}
+ \item[\Lref{widget_definition.hpp:control}] Normally a
widget definition inherits from tcontrol\_definition which
defines the
basic mandatory fields for a widget definition and a templated
load
function for the resolution. Most widgets don't add more
members to this
class.
- \item[Line \ref{widget_definition.hpp:resolution}] Normally a resolution
+ \item[\Lref{widget_definition.hpp:resolution}] Normally a resolution
definition inherits from tresolution\_definition\_ which define
the
basic mandatory fields for a resolution definition. Not all
widgets use
these members, but most do. Most widgets don't add more members
to this
@@ -49,13 +49,13 @@
minimum sizes for parts of their control.
\end{description}
-\item[cpp] Listing \ref{widget_definition.cpp} contains the sample code.
- \begin{description}
- \item[Line \ref{widget_definition.cpp:textdomain}] Every file in the
library
+\item[cpp] \Liref{widget_definition.cpp} contains the sample code.
+ \begin{description}
+ \item[\Lref{widget_definition.cpp:textdomain}] Every file in the library
is inside the ``wesnoth-lib'' text domain.
- \item[Line \ref{widget_definition.cpp:constructor}] The constructor
used is
+ \item[\Lref{widget_definition.cpp:constructor}] The constructor used is
pretty typical for all widgets.
- \item[Line \ref{widget_definition.cpp:resolution_constructor}] The
+ \item[\Lref{widget_definition.cpp:resolution_constructor}] The
constructor used is semi-typical. Resolutions that have their
own
members initialize them in the constructor, but also validate
mandatory
fields for their existence.
@@ -76,10 +76,10 @@
the percentage of the bar to be filled.
\begin{description}
- \item[Line \ref{progress_bar.cfg:textdomain}] Every file in the library
+ \item[\Lref{progress_bar.cfg:textdomain}] Every file in the library
is inside the ``wesnoth-lib'' text domain.
- \item[Line \ref{progress_bar.cfg:class}]
+ \item[\Lref{progress_bar.cfg:class}]
Beginning of the progress bar, this part is much better
documented in
the wiki %TODO ref
since this part is aimed at WML authors, duplicating that
effort here
@@ -94,9 +94,9 @@
dynamic content this file is also rather short.
\begin{description}
-\item[hpp] Listing \ref{window_builder.hpp} contains the sample code.
- \begin{description}
- \item[Line \ref{window_builder.hpp:control}] Normally a
+\item[hpp] \Liref{window_builder.hpp} contains the sample code.
+ \begin{description}
+ \item[\Lref{window_builder.hpp:control}] Normally a
window builder inherits from tbuilder\_control which defines the
basic mandatory fields for a window builder.
@@ -106,23 +106,23 @@
settings, e.g. the spacer defines its fixed size if needed.
\end{description}
-\item[cpp] Listing \ref{window_builder.cpp} contains the sample code.
- \begin{description}
- \item[Line \ref{window_builder.cpp:textdomain}] Every file in the
library
+\item[cpp] \Liref{window_builder.cpp} contains the sample code.
+ \begin{description}
+ \item[\Lref{window_builder.cpp:textdomain}] Every file in the library
is inside the ``wesnoth-lib'' text domain.
- \item[Line \ref{window_builder.cpp:constructor}] The constructor used is
+ \item[\Lref{window_builder.cpp:constructor}] The constructor used is
pretty typical for all widgets.
If the constructor initialize custom members it may add some
validation.
This is also true when the widget has a grid, like the listbox
or
multi\_page.
- \item[Line \ref{window_builder.cpp:build}]
+ \item[\Lref{window_builder.cpp:build}]
This build() is semi-typical, it creates the widget initializes
the
default fields and returns the created object.
Widgets with their own members initialize them after
initializing the
default members.
- \item[Line \ref{window_builder.cpp:wiki}]
+ \item[\Lref{window_builder.cpp:wiki}]
At the end of the file it contains two wiki comment sections:
The first defines a macro with a short description of the
widget.
@@ -140,28 +140,28 @@
invalidated in several functions.}
\begin{description}
-\item[hpp] Listing \ref{progress_bar.hpp} contains the sample code.
- \begin{description}
- \item[Line \ref{progress_bar.hpp:class}]
+\item[hpp] \Liref{progress_bar.hpp} contains the sample code.
+ \begin{description}
+ \item[\Lref{progress_bar.hpp:class}]
Most simple widgets derive from tcontrol, which is the base
class of the
visual widgets. Another common base is tcontainer or
tscrollbar\_container.
- \item[Line \ref{progress_bar.hpp:constructor}]
+ \item[\Lref{progress_bar.hpp:constructor}]
The class calls the control constructor with the number of
states, which
is the number of canvases used. Other then that it does the
initialization of its members. Some constructors do a bit more
processing but where a lot needs to be done, it's often
deferred to a
finalize function.
- \item[Line \ref{progress_bar.hpp:inherited}]
+ \item[\Lref{progress_bar.hpp:inherited}]
This section implements or overrides member functions of the
base class.
Some functions are pure virtual and need to be overridden
others to
change behaviour.\footnote{Of course a list of which functions
are
common the add here would be nice, however the library is still
too
volatile to do so, no need to create a soon out of date list.}
- \item[Line \ref{progress_bar.hpp:settersgetters}]
+ \item[\Lref{progress_bar.hpp:settersgetters}]
This section contains the setters and getters for the class. The
list below shows the common convention where T is the type of
the
setter/getter and ``foo'' the name of the member without
trailing
@@ -190,25 +190,25 @@
setter.
\end{description}
- \item[Line \ref{progress_bar.hpp:state}]
+ \item[\Lref{progress_bar.hpp:state}]
The state has the list of states available and normally has
COUNT as
last value, which in turn is used in the constructor to
initialize the
base class.
\end{description}
-\item[cpp] Listing \ref{progress_bar.cpp} contains the sample code.
- \begin{description}
- \item[Line \ref{progress_bar.cpp:textdomain}] Every file in the library
+\item[cpp] \Liref{progress_bar.cpp} contains the sample code.
+ \begin{description}
+ \item[\Lref{progress_bar.cpp:textdomain}] Every file in the library
is inside the ``wesnoth-lib'' text domain.
- \item[Line \ref{progress_bar.cpp:logheader}]
+ \item[\Lref{progress_bar.cpp:logheader}]
The common headers used for logging, this makes sure the output
of the
items always have the same format. Used by
LOG\_FOO \textless\textless{} LOG\_HEADER \textless\textless{}
"foo.\textbackslash{}n"; or
log\_scope(foo, LOG\_SCOPE); % check function signature
- \item[Line \ref{progress_bar.cpp:register}]
+ \item[\Lref{progress_bar.cpp:register}]
Registers a widget, this part is really volatile and still has
some
hoops and rings to jump through. Normally it works if not too
bad and
look through the other widgets to see how to fix it.
@@ -220,7 +220,7 @@
and read the comment above, dully add your class to the list
and be
happy.
- \item[Line \ref{progress_bar.cpp:get_control_type}]
+ \item[\Lref{progress_bar.cpp:get_control_type}]
Simple helper to get the human readable name of the class. The
first
version was inlined in the header, but that seems to be an ODR
violation. At least at some point a compiler or linker
complained, can't
@@ -274,15 +274,15 @@
to decide which widget s/he picks.
\begin{description}
-\item[hpp] Listing \ref{unit_attack.hpp} contains the sample code.
- \begin{description}
- \item[Line \ref{unit_attack.hpp:class}]
+\item[hpp] \Liref{unit_attack.hpp} contains the sample code.
+ \begin{description}
+ \item[\Lref{unit_attack.hpp:class}]
Defines the class itself, which normally inherits from tdialog.
Sometimes a class inherits from another class, but that class
then
derives from tdialog, for example the wml\_dialogs have a common base and
separate classes for left and right.
- \item[Line \ref{unit_attack.hpp:constructor}]
+ \item[\Lref{unit_attack.hpp:constructor}]
Dialogues are often created and then shown once before being
destroyed,
therefore the constructor often takes all parameters needed. Since the show
function shouldn't be overloaded the only other alternative would be member
@@ -294,18 +294,18 @@
the same. The window owning the widgets is destroyed after being shown and
a new one created upon the next call to show.
- \item[Line \ref{unit_attack.hpp:settersgetters}]
+ \item[\Lref{unit_attack.hpp:settersgetters}]
As said before there are often no setters, since all is set in
the
contructor. Most members also remain hidden since the caller has the
information. Only members that change are `exported'. The most common example
in
a class with a listbox, the last selected item is made public, since this is
often used as choice the user made.
- \item[Line \ref{unit_attack.hpp:window_id}]
+ \item[\Lref{unit_attack.hpp:window_id}]
This function is part of the window registration and only needs
to be
declared in the header, the definition will be provided by a macro.
- \item[Line \ref{unit_attack.hpp:pre_show}]
+ \item[\Lref{unit_attack.hpp:pre_show}]
This function is called after the window is created but before
being
shown. This is the point to set the members that point to a widget. As said
before every time the dialogue is shown a newly created window is shown, so
@@ -313,35 +313,35 @@
widgets with the proper content, if needed. Eg filling the languages in the
language selection dialogue.
- \item[Line \ref{unit_attack.hpp:post_show}]
+ \item[\Lref{unit_attack.hpp:post_show}]
Called after the dialogue is shown, this allows you to update
certain
statuses. E.g. if the dialogue is closed with the OK button set the selected
language to the newly selected language. You can also update it unconditionally
and let the caller test the status.
- \item[Line \ref{unit_attack.hpp:members}]
+ \item[\Lref{unit_attack.hpp:members}]
At this point the list of private members start.
\end{description}
-\item[cpp] Listing \ref{unit_attack.cpp} contains the sample code. Note some
+\item[cpp] \Liref{unit_attack.cpp} contains the sample code. Note some
parts are already described more verbose in the header and thus not mentioned
here.
\begin{description}
- \item[Line \ref{unit_attack.cpp:textdomain}]
+ \item[\Lref{unit_attack.cpp:textdomain}]
Like written for the widget, every file is inside the
`wesnoth-lib' text
domain.
- \item[Line \ref{unit_attack.cpp:wiki}]
+ \item[\Lref{unit_attack.cpp:wiki}]
Directly after the includes (inside the gui2 namespace) the wiki
documentation starts.
- \item[Line \ref{unit_attack.cpp:register}]
+ \item[\Lref{unit_attack.cpp:register}]
After the wiki documentation the registration code follows, it
defines
the window\_id function and does some other registration parts.
- \item[Line \ref{unit_attack.cpp:pre_show}]
+ \item[\Lref{unit_attack.cpp:pre_show}]
The pre\_show is already mentioned in the header file and it
the one
used here uses several static helper functions to do it's job.
@@ -351,17 +351,17 @@
\item[src/gui/dialogs/unit\_attack.cfg]
This file contains the WML that defines the widget. It should honour the
-restrains set in the wiki comment like \ref{unit_attack.cpp:wiki}. These
+restrains set in the wiki comment like \lref{unit_attack.cpp:wiki}. These
constrains set the minimum set of needed widgets and their types, and mentions
the optional widgets. How the widgets are placed and whether only the optional
ones are set is up to the designer of the dialog. The gui toolkit wiki has more
information on the subject. Still some parts are worth mentioning.
\begin{description}
- \item[Line \ref{unit_attack.cfg:textdomain}]
+ \item[\Lref{unit_attack.cfg:textdomain}]
Every file in the library is inside the ``wesnoth-lib'' text
domain.
- \item[Line \ref{unit_attack.cfg:defines}]
+ \item[\Lref{unit_attack.cfg:defines}]
With larger dialogs I often design them on paper and then
divide the
dialog in several sections. These sections often are turned into defines in
order to keep the main dialog rather simple. WML tends to be verbose and deeply
@@ -372,12 +372,12 @@
different definition of high resolution screens (this will be the first screen
using that feature, but that will be added later).
- \item[Line \ref{unit_attack.cfg:window}]
+ \item[\Lref{unit_attack.cfg:window}]
Not much to tell about this part, since it's all documented in
the wiki.
But do note that due to the defines above the grid in the window itself is
rather simple.
- \item[Line \ref{unit_attack.cfg:undefines}]
+ \item[\Lref{unit_attack.cfg:undefines}]
The local macros are no longer needed so undefine them, I
normally
undefine them in the oposite order of the definitions, I'm quite sure that's
not
actually needed, but it feels the right way\texttrademark.
Modified: trunk/doc/design/gui2/design_details.tex
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/doc/design/gui2/design_details.tex?rev=48646&r1=48645&r2=48646&view=diff
==============================================================================
--- trunk/doc/design/gui2/design_details.tex (original)
+++ trunk/doc/design/gui2/design_details.tex Sat Feb 26 09:54:02 2011
@@ -144,7 +144,7 @@
\section{Callbacks}
-\S~\ref{event_handling} describes the generic event handling for the widgets
but
+\Cref{event_handling} describes the generic event handling for the widgets but
in some cases a widget wants to notify other widgets of a state change. Parts
of
gui2 use simple C-style callbacks for that purpose, but using boost::function
makes better replacement. Therefore the code was analysed closer and another
Modified: trunk/doc/design/gui2/files_for_the_widget.tex
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/doc/design/gui2/files_for_the_widget.tex?rev=48646&r1=48645&r2=48646&view=diff
==============================================================================
--- trunk/doc/design/gui2/files_for_the_widget.tex (original)
+++ trunk/doc/design/gui2/files_for_the_widget.tex Sat Feb 26 09:54:02 2011
@@ -1,6 +1,6 @@
\chapter{Files for creating the widget}
-This chapter contains the files created in \S~\ref{sec:creating_the_widget},
these
+This chapter contains the files created in \cref{sec:creating_the_widget},
these
files aren't the real files added, but a slightly modified version; The
copyright headers are stripped to avoid taking up useless space. Some extra
comments are added to make referencing possible. This also means the files here
Modified: trunk/doc/design/gui2/files_for_the_window.tex
URL:
http://svn.gna.org/viewcvs/wesnoth/trunk/doc/design/gui2/files_for_the_window.tex?rev=48646&r1=48645&r2=48646&view=diff
==============================================================================
--- trunk/doc/design/gui2/files_for_the_window.tex (original)
+++ trunk/doc/design/gui2/files_for_the_window.tex Sat Feb 26 09:54:02 2011
@@ -1,7 +1,7 @@
\chapter{Files for creating the window}
This chapter like the previous one contains listings of files, this time for
-\S~\ref{sec:creating_the_window}. About the same is true for these files,
except
+\cref{sec:creating_the_window}. About the same is true for these files, except
we know the originals will change in the future.
\lstinputlisting[style=C++
_______________________________________________
Wesnoth-commits mailing list
[email protected]
https://mail.gna.org/listinfo/wesnoth-commits
