Thread: Documentation

Documentation

From
Guillaume Lelarge
Date:
Documentation for pgAdmin is really weak right now. Just to take an
example, I don't know where a plugin file is described.

The real question is how we do this. Right now, the documentation is a
set of HTML files. Which is fine for some people and not for others.
Kind of hard to get a consistent style. Kind of hard to get a good PDF
and CHM file out of it. Not sure we really need these formats, I'm sure
we want a consistent style.

The only way to get all these options, AFAICT, is to use Docbook. SGML
or XML. I have no problem working with Docbook, but I'm not sure
everyone feels the same. I really prefer XML because of the toolset we
can use (which seems, at least to me, in much better shape than the SGML
one).

Anyone has better ideas?


--
Guillaume
 http://www.postgresql.fr
 http://dalibo.com

Re: Documentation

From
Magnus Hagander
Date:
On Fri, Sep 24, 2010 at 10:29, Guillaume Lelarge <guillaume@lelarge.info> wrote:
> Documentation for pgAdmin is really weak right now. Just to take an
> example, I don't know where a plugin file is described.
>
> The real question is how we do this. Right now, the documentation is a
> set of HTML files. Which is fine for some people and not for others.
> Kind of hard to get a consistent style. Kind of hard to get a good PDF
> and CHM file out of it. Not sure we really need these formats, I'm sure
> we want a consistent style.
>
> The only way to get all these options, AFAICT, is to use Docbook. SGML
> or XML. I have no problem working with Docbook, but I'm not sure
> everyone feels the same. I really prefer XML because of the toolset we
> can use (which seems, at least to me, in much better shape than the SGML
> one).
>
> Anyone has better ideas?

I've chatted with Dave about this a couple of times lately. at the
time I suggested using RST and sphinx (http://sphinx.pocoo.org/). I
think this is a much nicer thing to work with than docbook. It might
not scale to as complex documentation (I'm not sure I'd like to see
the pg docs redone in it), but the pgadmin docs aren't that complex -
and probably shouldn't be.

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

Re: Documentation

From
Dave Page
Date:
On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge
<guillaume@lelarge.info> wrote:
> Documentation for pgAdmin is really weak right now. Just to take an
> example, I don't know where a plugin file is described.
>
> The real question is how we do this. Right now, the documentation is a
> set of HTML files. Which is fine for some people and not for others.
> Kind of hard to get a consistent style. Kind of hard to get a good PDF
> and CHM file out of it. Not sure we really need these formats, I'm sure
> we want a consistent style.
>
> The only way to get all these options, AFAICT, is to use Docbook. SGML
> or XML. I have no problem working with Docbook, but I'm not sure
> everyone feels the same. I really prefer XML because of the toolset we
> can use (which seems, at least to me, in much better shape than the SGML
> one).
>
> Anyone has better ideas?

Yeah, I was looking at this the other day, but ran out of time.
Looking at using Sphinx (http://sphinx.pocoo.org/).

I really don't want to use SGML or XML.

--
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise Postgres Company

Re: Documentation

From
Guillaume Lelarge
Date:
Le 24/09/2010 10:39, Dave Page a écrit :
> On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge
> <guillaume@lelarge.info> wrote:
>> Documentation for pgAdmin is really weak right now. Just to take an
>> example, I don't know where a plugin file is described.
>>
>> The real question is how we do this. Right now, the documentation is a
>> set of HTML files. Which is fine for some people and not for others.
>> Kind of hard to get a consistent style. Kind of hard to get a good PDF
>> and CHM file out of it. Not sure we really need these formats, I'm sure
>> we want a consistent style.
>>
>> The only way to get all these options, AFAICT, is to use Docbook. SGML
>> or XML. I have no problem working with Docbook, but I'm not sure
>> everyone feels the same. I really prefer XML because of the toolset we
>> can use (which seems, at least to me, in much better shape than the SGML
>> one).
>>
>> Anyone has better ideas?
>
> Yeah, I was looking at this the other day, but ran out of time.
> Looking at using Sphinx (http://sphinx.pocoo.org/).
>

Seems interesting. Just at the same time, we (Dalibo) get rid of our
documents in ReST format, so I'll still have to work with it for pgadmin :-/

Anyway, I need to test it a bit before going further on this.

> I really don't want to use SGML or XML.
>

I supposed so :)


--
Guillaume
 http://www.postgresql.fr
 http://dalibo.com

Re: Documentation

From
Magnus Hagander
Date:
On Fri, Sep 24, 2010 at 11:16, Guillaume Lelarge <guillaume@lelarge.info> wrote:
> Le 24/09/2010 10:39, Dave Page a écrit :
>> On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge
>> <guillaume@lelarge.info> wrote:
>>> Documentation for pgAdmin is really weak right now. Just to take an
>>> example, I don't know where a plugin file is described.
>>>
>>> The real question is how we do this. Right now, the documentation is a
>>> set of HTML files. Which is fine for some people and not for others.
>>> Kind of hard to get a consistent style. Kind of hard to get a good PDF
>>> and CHM file out of it. Not sure we really need these formats, I'm sure
>>> we want a consistent style.
>>>
>>> The only way to get all these options, AFAICT, is to use Docbook. SGML
>>> or XML. I have no problem working with Docbook, but I'm not sure
>>> everyone feels the same. I really prefer XML because of the toolset we
>>> can use (which seems, at least to me, in much better shape than the SGML
>>> one).
>>>
>>> Anyone has better ideas?
>>
>> Yeah, I was looking at this the other day, but ran out of time.
>> Looking at using Sphinx (http://sphinx.pocoo.org/).
>>
>
> Seems interesting. Just at the same time, we (Dalibo) get rid of our
> documents in ReST format, so I'll still have to work with it for pgadmin :-/

Why do you get rid of ReST, and what are you changing to?

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

Re: Documentation

From
Guillaume Lelarge
Date:
Le 24/09/2010 11:59, Magnus Hagander a écrit :
> On Fri, Sep 24, 2010 at 11:16, Guillaume Lelarge <guillaume@lelarge.info> wrote:
>> Le 24/09/2010 10:39, Dave Page a écrit :
>>> On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge
>>> <guillaume@lelarge.info> wrote:
>>>> Documentation for pgAdmin is really weak right now. Just to take an
>>>> example, I don't know where a plugin file is described.
>>>>
>>>> The real question is how we do this. Right now, the documentation is a
>>>> set of HTML files. Which is fine for some people and not for others.
>>>> Kind of hard to get a consistent style. Kind of hard to get a good PDF
>>>> and CHM file out of it. Not sure we really need these formats, I'm sure
>>>> we want a consistent style.
>>>>
>>>> The only way to get all these options, AFAICT, is to use Docbook. SGML
>>>> or XML. I have no problem working with Docbook, but I'm not sure
>>>> everyone feels the same. I really prefer XML because of the toolset we
>>>> can use (which seems, at least to me, in much better shape than the SGML
>>>> one).
>>>>
>>>> Anyone has better ideas?
>>>
>>> Yeah, I was looking at this the other day, but ran out of time.
>>> Looking at using Sphinx (http://sphinx.pocoo.org/).
>>>
>>
>> Seems interesting. Just at the same time, we (Dalibo) get rid of our
>> documents in ReST format, so I'll still have to work with it for pgadmin :-/
>
> Why do you get rid of ReST, and what are you changing to?
>

Not really because of ReST. Our real issue was the tool we used to build
HTML, PDF, etc. This tool was first written by dalibo, but nobody really
maintains it and it became more and more difficult to install it on
recent laptops. So, as you can see, not really an issue with ReST. And
we are changing to... dokuwiki. You surely know Damien felt in love with
this tool :)


--
Guillaume
 http://www.postgresql.fr
 http://dalibo.com

Re: Documentation

From
Guillaume Lelarge
Date:
Le 24/09/2010 12:06, Marek Černocký a écrit :
> It would be nice to choice format the gettext (or similar tool) know
> about. It's very difficult to track changes in the current documentation
> for translators.
>

Gettext really doesn't work for documentation. It's much harder to know
the context of each sentence. I'm translating the PostgreSQL manuel
since 7.4.7 IIRC, and I'm completely against using a .po toolchain for
the french translation. It could help to make it quicker and simpler to
update, but it would quickly degrade the quality of the translation. Of
course, this is only my opinion, and I know some that don't agree with
me on this.


--
Guillaume
 http://www.postgresql.fr
 http://dalibo.com

Re: Documentation

From
Dave Page
Date:
On Fri, Sep 24, 2010 at 11:13 AM, Guillaume Lelarge
<guillaume@lelarge.info> wrote:
> Not really because of ReST. Our real issue was the tool we used to build
> HTML, PDF, etc. This tool was first written by dalibo, but nobody really
> maintains it and it became more and more difficult to install it on
> recent laptops. So, as you can see, not really an issue with ReST. And
> we are changing to... dokuwiki. You surely know Damien felt in love with
> this tool :)

I know you're not suggesting it, but just so we're clear - the day
pgAdmin starts to use docuwiki is the day that Microsoft release a
Linux distro, Apple BSD licence all their code, pigs around the world
spontaneously sprout wings and world peace is declared.

When all those things happen at once, I'll gladly install docuwiki.

:-p

--
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise Postgres Company

Re: Documentation

From
Guillaume Lelarge
Date:
Le 24/09/2010 12:23, Dave Page a écrit :
> On Fri, Sep 24, 2010 at 11:13 AM, Guillaume Lelarge
> <guillaume@lelarge.info> wrote:
>> Not really because of ReST. Our real issue was the tool we used to build
>> HTML, PDF, etc. This tool was first written by dalibo, but nobody really
>> maintains it and it became more and more difficult to install it on
>> recent laptops. So, as you can see, not really an issue with ReST. And
>> we are changing to... dokuwiki. You surely know Damien felt in love with
>> this tool :)
>
> I know you're not suggesting it, but just so we're clear - the day
> pgAdmin starts to use docuwiki is the day that Microsoft release a
> Linux distro, Apple BSD licence all their code, pigs around the world
> spontaneously sprout wings and world peace is declared.
>
> When all those things happen at once, I'll gladly install docuwiki.
>
> :-p
>

:-D

(and yes, I'm not suggesting it)


--
Guillaume
 http://www.postgresql.fr
 http://dalibo.com

Re: Documentation

From
Magnus Hagander
Date:
On Fri, Sep 24, 2010 at 12:23, Dave Page <dpage@pgadmin.org> wrote:
> On Fri, Sep 24, 2010 at 11:13 AM, Guillaume Lelarge
> <guillaume@lelarge.info> wrote:
>> Not really because of ReST. Our real issue was the tool we used to build
>> HTML, PDF, etc. This tool was first written by dalibo, but nobody really
>> maintains it and it became more and more difficult to install it on
>> recent laptops. So, as you can see, not really an issue with ReST. And
>> we are changing to... dokuwiki. You surely know Damien felt in love with
>> this tool :)
>
> I know you're not suggesting it, but just so we're clear - the day
> pgAdmin starts to use docuwiki is the day that Microsoft release a
> Linux distro, Apple BSD licence all their code, pigs around the world
> spontaneously sprout wings and world peace is declared.
>
> When all those things happen at once, I'll gladly install docuwiki.

I think we should also require steve jobs to wear a suit during a presentation.

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

Re: Documentation

From
Dave Page
Date:
On Fri, Sep 24, 2010 at 12:16 PM, Magnus Hagander <magnus@hagander.net> wrote:
>> I know you're not suggesting it, but just so we're clear - the day
>> pgAdmin starts to use docuwiki is the day that Microsoft release a
>> Linux distro, Apple BSD licence all their code, pigs around the world
>> spontaneously sprout wings and world peace is declared.
>>
>> When all those things happen at once, I'll gladly install docuwiki.
>
> I think we should also require steve jobs to wear a suit during a presentation.

Well that just sets the barrier ridiculously high. There's no need to
go over the top.


--
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise Postgres Company

Re: Documentation

From
Marek Černocký
Date:
I comprehend your concern for quality. But now I have no clear info
about documentation changes. I would have to study git changelogs or do
other frustration work. It has impact on documentation translation
completeness and quality too.

I translate Gnome (which uses own tools for work with documentation
po/pot) and I don't see any problem with quality. Documentation
translator is usually the same as UI translator so he has knowledge
about application.

I thing the limit to translation quality is translator at first,
using .po is the matter in question.


Guillaume Lelarge píše v Pá 24. 09. 2010 v 12:22 +0200:
> Le 24/09/2010 12:06, Marek Černocký a écrit :
> > It would be nice to choice format the gettext (or similar tool) know
> > about. It's very difficult to track changes in the current documentation
> > for translators.
> >
>
> Gettext really doesn't work for documentation. It's much harder to know
> the context of each sentence. I'm translating the PostgreSQL manuel
> since 7.4.7 IIRC, and I'm completely against using a .po toolchain for
> the french translation. It could help to make it quicker and simpler to
> update, but it would quickly degrade the quality of the translation. Of
> course, this is only my opinion, and I know some that don't agree with
> me on this.
>
>



Re: Documentation

From
Guillaume Lelarge
Date:
Le 24/09/2010 15:16, Marek Černocký a écrit :
> I comprehend your concern for quality. But now I have no clear info
> about documentation changes. I would have to study git changelogs or do
> other frustration work. It has impact on documentation translation
> completeness and quality too.
>

You just need this command:

git diff REL-1_10_0_PATCHES -- docs/en_US

Which gives you 439 lines of changes (many are from binary files). With
this, you easily know changes on the documentation.

> I translate Gnome (which uses own tools for work with documentation
> po/pot) and I don't see any problem with quality. Documentation
> translator is usually the same as UI translator so he has knowledge
> about application.
>

Problem is not knowledge on the software. Translating a UI is a complete
different business than translating a documentation. There's not really
a context when you translate a UI, but there is one when you translate a
manual.

> I thing the limit to translation quality is translator at first,
> using .po is the matter in question.
>

Anyway, there are tools that helps you to build .po files from various
text formats. po4a for example.


--
Guillaume
 http://www.postgresql.fr
 http://dalibo.com

Re: Documentation

From
Marek Černocký
Date:
Guillaume Lelarge píše v Pá 24. 09. 2010 v 16:20 +0200:
> Le 24/09/2010 15:16, Marek Černocký a écrit :
> > I comprehend your concern for quality. But now I have no clear info
> > about documentation changes. I would have to study git changelogs or do
> > other frustration work. It has impact on documentation translation
> > completeness and quality too.
> >
>
> You just need this command:
>
> git diff REL-1_10_0_PATCHES -- docs/en_US
>
> Which gives you 439 lines of changes (many are from binary files). With
> this, you easily know changes on the documentation.
>
> > I translate Gnome (which uses own tools for work with documentation
> > po/pot) and I don't see any problem with quality. Documentation
> > translator is usually the same as UI translator so he has knowledge
> > about application.
> >
>
> Problem is not knowledge on the software. Translating a UI is a complete
> different business than translating a documentation. There's not really
> a context when you translate a UI, but there is one when you translate a
> manual.

Messages in .po file are sorted sequentially much like original
document. And messages are full sentences or even paragraphs. Context
you see directly. Documentation translation is exacting only for its
length.

Translating UI si difficult because you see isolated words or snippets
and you must search context in application.

> > I thing the limit to translation quality is translator at first,
> > using .po is the matter in question.
> >
>
> Anyway, there are tools that helps you to build .po files from various
> text formats. po4a for example.
>
>
> --
> Guillaume
>  http://www.postgresql.fr
>  http://dalibo.com
>



Re: Documentation

From
Guillaume Lelarge
Date:
Le 24/09/2010 11:16, Guillaume Lelarge a écrit :
> Le 24/09/2010 10:39, Dave Page a écrit :
>> On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge
>> <guillaume@lelarge.info> wrote:
>>> Documentation for pgAdmin is really weak right now. Just to take an
>>> example, I don't know where a plugin file is described.
>>>
>>> The real question is how we do this. Right now, the documentation is a
>>> set of HTML files. Which is fine for some people and not for others.
>>> Kind of hard to get a consistent style. Kind of hard to get a good PDF
>>> and CHM file out of it. Not sure we really need these formats, I'm sure
>>> we want a consistent style.
>>>
>>> The only way to get all these options, AFAICT, is to use Docbook. SGML
>>> or XML. I have no problem working with Docbook, but I'm not sure
>>> everyone feels the same. I really prefer XML because of the toolset we
>>> can use (which seems, at least to me, in much better shape than the SGML
>>> one).
>>>
>>> Anyone has better ideas?
>>
>> Yeah, I was looking at this the other day, but ran out of time.
>> Looking at using Sphinx (http://sphinx.pocoo.org/).
>>
>
> Seems interesting. Just at the same time, we (Dalibo) get rid of our
> documents in ReST format, so I'll still have to work with it for pgadmin :-/
>
> Anyway, I need to test it a bit before going further on this.
>

Seems good to me.

See
http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html.

It took me three hours to manually convert the current documentation.
There is also a possibility to change the theme. I'll try to do it on my
laptop.


--
Guillaume
 http://www.postgresql.fr
 http://dalibo.com

Re: Documentation

From
Dave Page
Date:
On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge
<guillaume@lelarge.info> wrote:
>
> See
> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html.
>
> It took me three hours to manually convert the current documentation.
> There is also a possibility to change the theme. I'll try to do it on my
> laptop.

Wow, that was quick (and unexpected!). There's some weirdness here,
but maybe that's just a markup issue:

http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect

---
If you select “Store password”, pgAdmin stores passwords you enter in
the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf
---

Otherwise it looks great. Couple of questions:

- Have you thought about how we might shoe-horn this into the build process?

- Have you tried the htmlhelp output on Windows and Linux/Mac?

--
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise Postgres Company

Re: Documentation

From
Magnus Hagander
Date:
On Mon, Sep 27, 2010 at 10:00, Dave Page <dpage@pgadmin.org> wrote:
> On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge
> <guillaume@lelarge.info> wrote:
>>
>> See
>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html.
>>
>> It took me three hours to manually convert the current documentation.
>> There is also a possibility to change the theme. I'll try to do it on my
>> laptop.
>
> Wow, that was quick (and unexpected!). There's some weirdness here,

Indeed. Nice job!


> but maybe that's just a markup issue:
>
> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect

I notice some weirdness on
http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/pgagent-install.html
as well:

1) I get scrollbars on all the "highlighted areas", that scrolls
exactly 1 pixel. Probably a CSS issue?
2) If I do view source to figure out why, I notice they have class
"highlight-python" - is there something that should be set to make it
not call it python? (I haven't investigated what it actually means
yet, no :P)


> Otherwise it looks great. Couple of questions:
>
> - Have you thought about how we might shoe-horn this into the build process?

One direct question here - is it going to be a PITA on Windows? I've
never tried it there, it might be?

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/

Re: Documentation

From
Thom Brown
Date:
On 27 September 2010 09:00, Dave Page <dpage@pgadmin.org> wrote:
> On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge
> <guillaume@lelarge.info> wrote:
>>
>> See
>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html.
>>
>> It took me three hours to manually convert the current documentation.
>> There is also a possibility to change the theme. I'll try to do it on my
>> laptop.
>
> Wow, that was quick (and unexpected!). There's some weirdness here,
> but maybe that's just a markup issue:
>
> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect
>
> ---
> If you select “Store password”, pgAdmin stores passwords you enter in
> the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf
> ---

That's because those paragraphs are justified.  Just alter the css to
use "text-align: left;" instead.

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Re: Documentation

From
Thom Brown
Date:
On 27 September 2010 09:06, Magnus Hagander <magnus@hagander.net> wrote:
> On Mon, Sep 27, 2010 at 10:00, Dave Page <dpage@pgadmin.org> wrote:
>> On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge
>> <guillaume@lelarge.info> wrote:
>>>
>>> See
>>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html.
>>>
>>> It took me three hours to manually convert the current documentation.
>>> There is also a possibility to change the theme. I'll try to do it on my
>>> laptop.
>>
>> Wow, that was quick (and unexpected!). There's some weirdness here,
>
> Indeed. Nice job!
>
>
>> but maybe that's just a markup issue:
>>
>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect
>
> I notice some weirdness on
> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/pgagent-install.html
> as well:
>
> 1) I get scrollbars on all the "highlighted areas", that scrolls
> exactly 1 pixel. Probably a CSS issue?

If you remove the ability to scroll the overflow, text on some pages,
or small screens, will flow outside the container.

> 2) If I do view source to figure out why, I notice they have class
> "highlight-python" - is there something that should be set to make it
> not call it python? (I haven't investigated what it actually means
> yet, no :P)

The highlight-python class has no bearing on style as nothing refers
to that class in any CSS file.  You can safely rename it, but it will
have no visual effect.

But great work Guillaume :)  Very slick.  And I see you've also
updated the screenshots too, so it includes the mystery history box!
:D  (although no textual references to it ATM)

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Re: Documentation

From
Dave Page
Date:
On Mon, Sep 27, 2010 at 9:11 AM, Thom Brown <thom@linux.com> wrote:
> On 27 September 2010 09:00, Dave Page <dpage@pgadmin.org> wrote:
>> Wow, that was quick (and unexpected!). There's some weirdness here,
>> but maybe that's just a markup issue:
>>
>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect
>>
>> ---
>> If you select “Store password”, pgAdmin stores passwords you enter in
>> the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf
>> ---
>
> That's because those paragraphs are justified.  Just alter the css to
> use "text-align: left;" instead.

I'm referring to the missing /'s, though the justification does look a
little odd on that line too (for the reason you state).



--
Dave Page
Blog: http://pgsnake.blogspot.com
Twitter: @pgsnake

EnterpriseDB UK: http://www.enterprisedb.com
The Enterprise Postgres Company

Re: Documentation

From
Thom Brown
Date:
On 27 September 2010 09:26, Dave Page <dpage@pgadmin.org> wrote:
> On Mon, Sep 27, 2010 at 9:11 AM, Thom Brown <thom@linux.com> wrote:
>> On 27 September 2010 09:00, Dave Page <dpage@pgadmin.org> wrote:
>>> Wow, that was quick (and unexpected!). There's some weirdness here,
>>> but maybe that's just a markup issue:
>>>
>>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect
>>>
>>> ---
>>> If you select “Store password”, pgAdmin stores passwords you enter in
>>> the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf
>>> ---
>>
>> That's because those paragraphs are justified.  Just alter the css to
>> use "text-align: left;" instead.
>
> I'm referring to the missing /'s, though the justification does look a
> little odd on that line too (for the reason you state).

Oh yeah!  Yes, nothing to do with CSS there. :)  Might be something to
do with it automatically turning it into a link, but doesn't like
backslashes.

--
Thom Brown
Twitter: @darkixion
IRC (freenode): dark_ixion
Registered Linux user: #516935

Re: Documentation

From
Christophe Chauvet
Date:
Hi

I wrote a PostgreSQL syntax highlighting [1] for Pygments (used by sphinx for code)

I don't know if it may be useful for the documentation.

Regards,

[1] : https://bitbucket.org/kryskool/pygments-postgresql/

On Sun, 26 Sep 2010 22:50:19 +0200, Guillaume Lelarge <guillaume@lelarge.info> wrote:
> Le 24/09/2010 11:16, Guillaume Lelarge a écrit :
>> Le 24/09/2010 10:39, Dave Page a écrit :
>>> On Fri, Sep 24, 2010 at 9:29 AM, Guillaume Lelarge
>>> <guillaume@lelarge.info> wrote:
>>>> Documentation for pgAdmin is really weak right now. Just to take an
>>>> example, I don't know where a plugin file is described.
>>>>
>>>> The real question is how we do this. Right now, the documentation is a
>>>> set of HTML files. Which is fine for some people and not for others.
>>>> Kind of hard to get a consistent style. Kind of hard to get a good PDF
>>>> and CHM file out of it. Not sure we really need these formats, I'm
> sure
>>>> we want a consistent style.
>>>>
>>>> The only way to get all these options, AFAICT, is to use Docbook. SGML
>>>> or XML. I have no problem working with Docbook, but I'm not sure
>>>> everyone feels the same. I really prefer XML because of the toolset we
>>>> can use (which seems, at least to me, in much better shape than the
> SGML
>>>> one).
>>>>
>>>> Anyone has better ideas?
>>>
>>> Yeah, I was looking at this the other day, but ran out of time.
>>> Looking at using Sphinx (http://sphinx.pocoo.org/).
>>>
>>
>> Seems interesting. Just at the same time, we (Dalibo) get rid of our
>> documents in ReST format, so I'll still have to work with it for pgadmin
> :-/
>>
>> Anyway, I need to test it a bit before going further on this.
>>
>
> Seems good to me.
>
> See
> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html.
>
> It took me three hours to manually convert the current documentation.
> There is also a possibility to change the theme. I'll try to do it on my
> laptop.
>
>
> --
> Guillaume
>  http://www.postgresql.fr
>  http://dalibo.com
>
> --
> Sent via pgadmin-hackers mailing list (pgadmin-hackers@postgresql.org)
> To make changes to your subscription:
> http://www.postgresql.org/mailpref/pgadmin-hackers


Re: Documentation

From
Guillaume Lelarge
Date:
Le 27/09/2010 10:00, Dave Page a écrit :
> On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge
> <guillaume@lelarge.info> wrote:
>>
>> See
>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html.
>>
>> It took me three hours to manually convert the current documentation.
>> There is also a possibility to change the theme. I'll try to do it on my
>> laptop.
>
> Wow, that was quick (and unexpected!). There's some weirdness here,
> but maybe that's just a markup issue:
>
> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect
>
> ---
> If you select “Store password”, pgAdmin stores passwords you enter in
> the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf
> ---
>

Yes, there are probably a lot of weirdness. Not because of the tool, but
because of me. I think it would be hard for me to work on this before
this weekend. Crappy hotel (and when I say crappy, I really mean it...
or probably worse), and crappy internet connection.

> Otherwise it looks great. Couple of questions:
>
> - Have you thought about how we might shoe-horn this into the build process?
>

Not yet. Actually, my main issue is "what should we put on the repo?".
Only the .rst files? the whole project, including the Makefile? I didn't
set my mind yet on this issue.

> - Have you tried the htmlhelp output on Windows and Linux/Mac?
>

Not yet :) I'm waiting to have a windows box before working on this (ie
get back to my home).


--
Guillaume
 http://www.postgresql.fr
 http://dalibo.com

Re: Documentation

From
Guillaume Lelarge
Date:
Le 27/09/2010 10:06, Magnus Hagander a écrit :
> On Mon, Sep 27, 2010 at 10:00, Dave Page <dpage@pgadmin.org> wrote:
>> On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge
>> <guillaume@lelarge.info> wrote:
>>>
>>> See
>>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html.
>>>
>>> It took me three hours to manually convert the current documentation.
>>> There is also a possibility to change the theme. I'll try to do it on my
>>> laptop.
>>
>> Wow, that was quick (and unexpected!). There's some weirdness here,
>
> Indeed. Nice job!
>

Thanks.

>> but maybe that's just a markup issue:
>>
>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect
>
> I notice some weirdness on
> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/pgagent-install.html
> as well:
>
> 1) I get scrollbars on all the "highlighted areas", that scrolls
> exactly 1 pixel. Probably a CSS issue?
> 2) If I do view source to figure out why, I notice they have class
> "highlight-python" - is there something that should be set to make it
> not call it python? (I haven't investigated what it actually means
> yet, no :P)
>

Well, actually, I think we should have a customized theme, so that the
docs look like our website.

>> Otherwise it looks great. Couple of questions:
>>
>> - Have you thought about how we might shoe-horn this into the build process?
>
> One direct question here - is it going to be a PITA on Windows? I've
> never tried it there, it might be?
>

Shouldn't be. I didn't ask for it, but you can have a .bat file to build
the documentation. Of course, next question is: "is it going to be a
PITA to install python and its plugins on Windows?" I don't have an
answer on this one.


--
Guillaume
 http://www.postgresql.fr
 http://dalibo.com

Re: Documentation

From
Guillaume Lelarge
Date:
Le 27/09/2010 10:17, Thom Brown a écrit :
> On 27 September 2010 09:06, Magnus Hagander <magnus@hagander.net> wrote:
>> On Mon, Sep 27, 2010 at 10:00, Dave Page <dpage@pgadmin.org> wrote:
>>> On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge
>>> <guillaume@lelarge.info> wrote:
>>>>
>>>> See
>>>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html.
>>>>
>>>> It took me three hours to manually convert the current documentation.
>>>> There is also a possibility to change the theme. I'll try to do it on my
>>>> laptop.
>>>
>>> Wow, that was quick (and unexpected!). There's some weirdness here,
>>
>> Indeed. Nice job!
>>
>>
>>> but maybe that's just a markup issue:
>>>
>>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect
>>
>> I notice some weirdness on
>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/pgagent-install.html
>> as well:
>>
>> 1) I get scrollbars on all the "highlighted areas", that scrolls
>> exactly 1 pixel. Probably a CSS issue?
>
> If you remove the ability to scroll the overflow, text on some pages,
> or small screens, will flow outside the container.
>
>> 2) If I do view source to figure out why, I notice they have class
>> "highlight-python" - is there something that should be set to make it
>> not call it python? (I haven't investigated what it actually means
>> yet, no :P)
>
> The highlight-python class has no bearing on style as nothing refers
> to that class in any CSS file.  You can safely rename it, but it will
> have no visual effect.
>

It could have an effect with other tags. I didn't use every tag that
sphinx allows.

> But great work Guillaume :)  Very slick.

Thanks :)

>  And I see you've also
> updated the screenshots too, so it includes the mystery history box!
> :D  (although no textual references to it ATM)
>

The screenshots should be updated on the current website too.


--
Guillaume
 http://www.postgresql.fr
 http://dalibo.com

Re: Documentation

From
Guillaume Lelarge
Date:
Le 27/09/2010 10:42, Thom Brown a écrit :
> On 27 September 2010 09:26, Dave Page <dpage@pgadmin.org> wrote:
>> On Mon, Sep 27, 2010 at 9:11 AM, Thom Brown <thom@linux.com> wrote:
>>> On 27 September 2010 09:00, Dave Page <dpage@pgadmin.org> wrote:
>>>> Wow, that was quick (and unexpected!). There's some weirdness here,
>>>> but maybe that's just a markup issue:
>>>>
>>>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect
>>>>
>>>> ---
>>>> If you select “Store password”, pgAdmin stores passwords you enter in
>>>> the ~/.pgpass file under Unix or :file:%APPDATA%postgresqlpgpass.conf
>>>> ---
>>>
>>> That's because those paragraphs are justified.  Just alter the css to
>>> use "text-align: left;" instead.
>>
>> I'm referring to the missing /'s, though the justification does look a
>> little odd on that line too (for the reason you state).
>
> Oh yeah!  Yes, nothing to do with CSS there. :)  Might be something to
> do with it automatically turning it into a link, but doesn't like
> backslashes.
>

Will fix it in a few days.


--
Guillaume
 http://www.postgresql.fr
 http://dalibo.com

Re: Documentation

From
Magnus Hagander
Date:
On Mon, Sep 27, 2010 at 18:26, Guillaume Lelarge <guillaume@lelarge.info> wrote:
> Le 27/09/2010 10:06, Magnus Hagander a écrit :
>> On Mon, Sep 27, 2010 at 10:00, Dave Page <dpage@pgadmin.org> wrote:
>>> On Sun, Sep 26, 2010 at 9:50 PM, Guillaume Lelarge
>>> <guillaume@lelarge.info> wrote:
>>>>
>>>> See
>>>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/index.html.
>>>>
>>>> It took me three hours to manually convert the current documentation.
>>>> There is also a possibility to change the theme. I'll try to do it on my
>>>> laptop.
>>>
>>> Wow, that was quick (and unexpected!). There's some weirdness here,
>>
>> Indeed. Nice job!
>>
>
> Thanks.
>
>>> but maybe that's just a markup issue:
>>>
>>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/connect.html#connect
>>
>> I notice some weirdness on
>> http://developer.pgadmin.org/~guillaume/pgadmin_docs/_build/html/pgagent-install.html
>> as well:
>>
>> 1) I get scrollbars on all the "highlighted areas", that scrolls
>> exactly 1 pixel. Probably a CSS issue?
>> 2) If I do view source to figure out why, I notice they have class
>> "highlight-python" - is there something that should be set to make it
>> not call it python? (I haven't investigated what it actually means
>> yet, no :P)
>>
>
> Well, actually, I think we should have a customized theme, so that the
> docs look like our website.

+1.


>>> Otherwise it looks great. Couple of questions:
>>>
>>> - Have you thought about how we might shoe-horn this into the build process?
>>
>> One direct question here - is it going to be a PITA on Windows? I've
>> never tried it there, it might be?
>>
>
> Shouldn't be. I didn't ask for it, but you can have a .bat file to build
> the documentation. Of course, next question is: "is it going to be a
> PITA to install python and its plugins on Windows?" I don't have an
> answer on this one.

Well, that's really what was my question :-)

--
 Magnus Hagander
 Me: http://www.hagander.net/
 Work: http://www.redpill-linpro.com/