Re: Epiphany-Extension Help file

[Joachim Noreiko <jnoreiko yahoo com>]

--- Baptiste Mille-Mathias
<baptiste millemathias gmail com> wrote:
> 
> For information, I finish a first step of the
> documentation of
> epiphany-extensions. You can found an html export at
>
http://www.kinoa.info/GNOME/epiphany-extensions/help/
> and the tarball of the docbok document at
>
http://www.kinoa.info/GNOME/epiphany-extensions/help/epiphany-extensions-help.tar.gz
> 
> The document is not totally finished, because I lack
> some information
> about some extensions, and I was not able to contact
> the appropriate
> maintainers, but I think around 80 % is done.
> 
> I would like to know if you can review this help
> file, in order to
> ship a first version for GNOME 2.14.1

My comments below....

'Epiphany Extensions Manual 1.0' -- don't include a
version in the title

Introduction

'companions' -- this expression is a bit too abstract.
'extend the capabilities' perhaps? 'add extra features
to'? This is partly what you're saying in the second
sentence, but it should perhaps come first.
Some information is needed: are these extensions
readily available with Epi, or must I install them to
have access to them?

'complete some existing.' -- makes it sound like
without the extension they're rubbish.

'Epiphany' -- needs <application> tags throughout. One
way to do this, as suggested in the template DocBook
file, is to define
<!ENTITY app
"<application>MY-GNOME-APPLICATION</application>">

Actions

'Actions extension' -- The Actions extension. Don't
know if this should have an  <application> tag. It
definitely needs some form of markup. Ask Shaun. 

'contextual menu,' -- context menu

'Actions are stored in ephy-actions.xml in folder
~/.gnome2/epiphany/' -- I can create, edit, delete
actions with the GUI. Hide scary geek stuff like this
at the end of the section.

'2.4.&#8195;About Epiphany Extensions' -- Do you mean
'About Actions Extension'? I'm not sure if the manual
is the right place for developer credits -- ask Shaun.

'Click button Add to add a new action' -- you don't
need to say 'button'. Or if you feel you do, 'the Add
button'.

'To edit an action' -- This should be a full sentence,
ending with a colon. 'To edit an action, do the
following:'

Ad Blocker

Ad Blocker extension -- same as before: 'The' and a
tag.

permits to block ad banners on a website; It allows --
a . not a ;

silently disregard -- what does this mean? If you mean
it hides ads, just say that.

Perl regular expression -- s/$/s/  ;)

Enter the URL of a page you want to read and you know
its content change often, then choose View &#8594;
Auto Reload to enable auto reload, then Epiphany will
refresh each time the content change. -- looks like 2
sentences have got mixed up.

'This function is very handy' -- avoid opinion &
colloquial language
(http://developer.gnome.org/documents/style-guide/fundamentals-3.html).
(Though I agree, it sounds VERY handy!!!! 'Use this
function to...' maybe?

AutoScroll

s/you mouse/your mouse
s/;/./ -- sentence too long

Use Auto Scroll -- s/Use/Using/ -- and the same to all
headings throughout.
Format this section into a numbered list of steps.

Certificates

Certificates extension give -- The Certificates
extension gives

When you browse a secured website, a locked padlock
appears on the left of the statusbar, when the
Certificates extension is activated, you can click on
the padlock, it will displayed the certificate
information. -- cut into two sentences.

Gestures

Gestures allows you to use Mouse Gesture, Mouse
gestures provide an easy way to quickly perform
actions in Epiphany without even having to move the
mouse outside of the browser window.
Gestures allows you to use Mouse Gestures. Mouse
gestures ...

'without even having to move the mouse outside of the
browser window' -- what does this mean? How about
'perform actions by moving the mouse to draw a shape.'

-----------

I'll leave off there as it's dinnertime :)

I've been REALLY nitpicky, and I hope that's not going
to discourage you.
Overall, this is great work, and it's nicely divided
up into clear sections, and it looks like you've
covered all the information.
 
The biggest problem is the sentences that are too
long, and really look like two or more sentences with
commas. Chop those up :)

Joachim

PS. Oh, and it doesn't validate... ;)


		
___________________________________________________________ 
Yahoo! Photos ? NEW, now offering a quality print service from just 8p a photo http://uk.photos.yahoo.com