Update of the Photo Section

[Phil Bull]

Hi Stephanie,

On Tue, 2008-09-30 at 13:09 -0700, Stephanie Mardell wrote:
> This patch does not seem to have been applied. Is there an issue or
> have I missed something?

Sorry for the delay in getting back to you, I've only just found time to
look over your patch.

It seems that a significant amount of the material in the patch has been
copied directly from the F-Spot manual. We already ship the F-Spot
manual, so we can just link to it instead; this saves us from
maintaining multiple versions of the same text, and is pretty convenient
for users too. Copying material unattributed may also present an issue
with copyright. As such, I'm afraid that I can't apply your patch in its
current form - the copied material needs to be removed and replaced with
links to the F-Spot manual (see below). This shouldn't be too difficult,
as long as the copied text can be identified.

I also noticed a few minor problems with the DocBook markup in the
patch. I've listed the issues below with some advice on how to correct
them.

VALIDATION ERRORS

There were also a few validation errors, which must be fixed before a
patch can be applied. Validation ensures that a document follows the
DocBook standard and so will be read as intended by Yelp and other
programs. You can validate a document using the following command:

xmllint --valid --noout --noent filename.xml

Replace filename.xml with the path of the file you want to validate. If
the document validates, the command will give no output. Otherwise,
it'll give you a line number and a description of any errors that it
finds.

USING SECTIONS

There were a couple of lines in the patch which look like
"<para><title>Creating Tags</title></para>". The <title> tag can't be
used inside the paragraph tag. <title> is used to give the title of a
section, so is only usually used inside a section tag such as <sect1>.
Here's an example:

<sect2 id="section-id-which-you-choose" status="writing">
	<title>Creating tags</title>
	...Other tags, such as para...
</sect2>

Correctly structuring DocBook documents isn't easy, since it's a much
stricter markup language than HTML. A general rule of thumb to use is
that "if you think a block of text should have a title, enclose it in
appropriate <section> tags". The appropriate tags depend on what the
current parent tag is (e.g. if the parent tag is <sect1>, the
appropriate section tag is <sect2>).

LISTS AND PROCEDURES

There are three different types of list in DocBook: orderedlist
(numbered), itemizedlist (bulleted) and procedure (step-by-step numbered
list, displayed identically to orderedlist). If you want a list of
bulleted or numbered points, you must use one of these list tags - you
can't place a <step><para>Text...</para></step> structure straight into
the section, as that wouldn't be valid DocBook markup.

Here is an example <sect2>, which you can copy into any <sect1> and view
in Yelp:

<sect2>
	<title>Lists!</title>

	<para>This is a bulleted list:</para>
	<itemizedlist>
		<listitem>
			<para>Item one</para>
		</listitem>
		<listitem>
			<para>Item two</para>
		</listitem>
	</itemizedlist>

	<para>This is a numbered list:</para>
	<orderedlist>
		<listitem>
			<para>Item one</para>
		</listitem>
		<listitem>
			<para>Item two</para>
		</listitem>
	</orderedlist>

	<para>This is a procedure:</para>
	<procedure>
		<step>
			<para>This is step one</para>
		</step>
		<step>
			<para>This is step two</para>
		</step>
	</procedure>
</sect2>

ADDING LINKS

To add links to another document, use the following sort of markup:

<para>See the <ulink type="help" url="ghelp:f-spot">F-Spot
manual</ulink> for details.</para>

To add a link to a section within another document, find the ID of the
section by right-clicking a link to the section in Yelp (e.g. on the
table of contents of the document containing the section), select "Copy
Link Address", paste the link into a text document and look for the text
after the hash. For example, the "Enjoying your photos" section of the
F-Spot manual has the following link address:

file:///usr/share/gnome/help/f-spot/C/f-spot.xml#enjoying

>From this, we see that the document name is "f-spot" (you must remove
the ".xml" bit) and the section ID is "enjoying". Hence, we use the
following markup to link to the section:

<para>See the <ulink type="help" url="ghelp:f-spot#enjoying">F-Spot
manual</ulink> for details.</para>

Sorry once again for the delay in reviewing your patch. I hope you find
this email useful; please do let me know if I haven't explained
something well or if you have any questions about your patch or DocBook
in general (it definitely takes some getting used to).

Thanks,

Phil

-- 
Phil Bull
https://launchpad.net/people/philbull