upstream/wesnoth
1
0
Fork 0
mirror of https://github.com/wesnoth/wesnoth synced 2025-04-29 19:02:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve linking to references.

Browse Source 
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.
This commit is contained in:
Mark de Wever 2011-02-26 08:54:02 +00:00
parent 65dca6e323
commit 54ceda8497
5 changed files with 72 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
doc/design/gui2.sty
View File

@ -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}}

90
doc/design/gui2/creating_widgets_and_dialogs.tex
View File

@ -33,14 +33,14 @@ the files after which I dive more into the implementation of the file.
a certain definition of a progress bar.
\begin{description}
\item[hpp] Listing \ref{widget_definition.hpp} contains the sample code.
\item[hpp] \Liref{widget_definition.hpp} contains the sample code.
\begin{description}
\item[Line \ref{widget_definition.hpp:control}] Normally a
\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 @@ the files after which I dive more into the implementation of the file.
minimum sizes for parts of their control.
\end{description}
\item[cpp] Listing \ref{widget_definition.cpp} contains the sample code.
\item[cpp] \Liref{widget_definition.cpp} contains the sample code.
\begin{description}
\item[Line \ref{widget_definition.cpp:textdomain}] Every file in the library
\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 files after which I dive more into the implementation of the file.
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 @@ the files after which I dive more into the implementation of the file.
dynamic content this file is also rather short.
\begin{description}
\item[hpp] Listing \ref{window_builder.hpp} contains the sample code.
\item[hpp] \Liref{window_builder.hpp} contains the sample code.
\begin{description}
\item[Line \ref{window_builder.hpp:control}] Normally a
\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 @@ the files after which I dive more into the implementation of the file.
settings, e.g. the spacer defines its fixed size if needed.
\end{description}
\item[cpp] Listing \ref{window_builder.cpp} contains the sample code.
\item[cpp] \Liref{window_builder.cpp} contains the sample code.
\begin{description}
\item[Line \ref{window_builder.cpp:textdomain}] Every file in the library
\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 @@ the files after which I dive more into the implementation of the file.
invalidated in several functions.}
\begin{description}
\item[hpp] Listing \ref{progress_bar.hpp} contains the sample code.
\item[hpp] \Liref{progress_bar.hpp} contains the sample code.
\begin{description}
\item[Line \ref{progress_bar.hpp:class}]
\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 @@ the files after which I dive more into the implementation of the file.
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.
\item[cpp] \Liref{progress_bar.cpp} contains the sample code.
\begin{description}
\item[Line \ref{progress_bar.cpp:textdomain}] Every file in the library
\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 @@ the files after which I dive more into the implementation of the file.
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 @@ the files after which I dive more into the implementation of the file.
to decide which widget s/he picks.
\begin{description}
\item[hpp] Listing \ref{unit_attack.hpp} contains the sample code.
\item[hpp] \Liref{unit_attack.hpp} contains the sample code.
\begin{description}
\item[Line \ref{unit_attack.hpp:class}]
\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 dialogue is shown twice (using the \emph{same} object) the widgets won't be
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 @@ setting the pointers can be unconditional. This is also the place to fill the
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 @@ used here uses several static helper functions to do it's job.
\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 @@ with other macros. The BIG in the names are just because I want to make a
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.

2
doc/design/gui2/design_details.tex
View File

@ -144,7 +144,7 @@ increment operator.
\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

2
doc/design/gui2/files_for_the_widget.tex
View File

@ -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

2
doc/design/gui2/files_for_the_window.tex
View File

@ -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++