headers
Don Scorgie | 4 Apr 2007 20:17

Plan for the Yelp Spoon branch

Hi,

A long while ago (okay, a couple of weeks ago) shaunm asked that I post
an outline of my plan for the yelp-spoon branch here.  This info
(together with the similar plan shuanm's promised to write for the
yelp-document branch) should help us formulate a plan for how to merge
all this stuff.  So, without further ado, here we go.

The plan is to roughly follow the current structure in yelp-toc.c, but
rip out the scrollkeeper stuff, man page and info page stuff and replace
it with calls into spoon.  Right now, the scrollkeeper is done, the info
stuff is started and the man page stuff, not so much (see later).

In addition, the YelpDocInfo stuff from yelp-utils will go the way of
the dodo, as it'll be superseded by spoon structures.  This should
simplify yelp-toc-pager (at a minimum - no more hash tables and
many-nested loops or filling in YelpDocInfo structs).  In addition, the
yelp-window file will be cleared out somewhat as the various YelpDocInfo
stuff will need to be altered to calls into Spoon.  I haven't yet
figured out exactly what changes are required in yelp-window, but I will
do soon.  I am planning on keeping (roughly) the same structure in all
the files (at least, nothing that should strongly contradict with
shaunm's own yelp-document branch).

Unfortunately, fd.o hasn't yet responded to my request for SVN storage
for Spoon, so testing out the new yelp is difficult (unless you pester
me for a dump from Spoon SVN from my machine).

Finally, the plan for man pages in Spoon...
I had planned on ripping the yelp version of the man page TOC stuff, but
(Continue reading)

Permalink | Reply | 0 comments |
headers
Shaun McCance | 5 Apr 2007 19:50
Picon
Gravatar

Plan for the YelpDocument branch

A long while ago (okay, a couple of weeks ago), I asked Don to
post an outline of his plan for the yelp-spoon branch, and said
I'd do the same for the yelp-document branch.  Don lived up to
his end, so here's mine.

YelpDocument will be replacing YelpPager as the API for getting
HTML pages from stuff.  YelpPager's API basically assumes that
we will process a given document once, and it fires off signals
every time it gets a page.  This has disadvantages:

1) Pre-paginated documents (e.g. Mallard) are forced into a
model that just doesn't make sense.  The price of this will
be performance penalties.

2) YelpWindow (or any other hypothetical pager consumer) has
to have a lot of logic to track which page it wants and when
it's available and all that crap.

3) There's no way for the pager to know which pages are being
viewed, or when pages were last viewed, or anything like that.
This makes it very difficult to clean up.

4) Same statement as above.  This makes it impossible for the
pager to push updated versions of a page. This means that reload
logic has to be handled inside YelpWindow, and it has no way of
signaling to other windows that they should also reload.

The YelpPager API was my brainchild from way back in 2003 when
I first took over Yelp.  It encapsulated the way Yelp already
worked into a single API, so that YelpWindow wouldn't have to
(Continue reading)

Permalink | Reply | 2 comments |
headers
Don Scorgie | 5 Apr 2007 22:06

Re: Plan for the YelpDocument branch

Hi,

On Thu, 2007-04-05 at 12:50 -0500, Shaun McCance wrote:
<snip lots of interesting stuff>
> 
> YelpWindow will, of course, have to be changed considerably to
> use YelpDocument.  Preferably, we'd want a factory API where
> we can hand it a URI/filename and just get a YelpDocument back.
> Since a YelpDocument could hold whatever metadata it needs to,
> there's really no reason for YelpDocInfo.  (At least not in the
> header files.  A small struct might be convenient in the TOC.)

Excellent.  The YelpDocInfo stuff is causing me some problems right
now ;)

> 
> I had envisioned the following document types:
>   YelpDocbook: a single DocBook document
>   YelpInfo:    a single info document
>   YelpInfoToc: the TOC listings for info pages
>   YelpMallard: a single Mallard document
>   YelpMan:     a single man page
>   YelpManToc:  the TOC listings for man pages
>   YelpSearch:  a singleton document managing all searches
>   YelpToc:     the main TOC listings
> 
> Clearly, the three bits that deal with TOCs needs to be
> coordinated with Don's Spoon work.  But the rest of them
> should be largely independent of that work.
(Continue reading)

Permalink | Reply | 1 comment |
headers
Shaun McCance | 6 Apr 2007 17:24
Picon
Gravatar

Re: Plan for the YelpDocument branch

On Thu, 2007-04-05 at 21:06 +0100, Don Scorgie wrote:
> > I had envisioned the following document types:
> >   YelpDocbook: a single DocBook document
> >   YelpInfo:    a single info document
> >   YelpInfoToc: the TOC listings for info pages
> >   YelpMallard: a single Mallard document
> >   YelpMan:     a single man page
> >   YelpManToc:  the TOC listings for man pages
> >   YelpSearch:  a singleton document managing all searches
> >   YelpToc:     the main TOC listings
> > 
> > Clearly, the three bits that deal with TOCs needs to be
> > coordinated with Don's Spoon work.  But the rest of them
> > should be largely independent of that work.
> 
> The Spoon stuff should remove virtually all the parsing code in the
> TOCs, so each YelpDocument should only require a couple of simple calls
> (see the yelp-spoon branch yelp-toc-pager.c for how simplified the main
> TOC stuff becomes ;) ).

I'd intended to have the multiple TOC documents specifically
because yelp-toc-pager has too much unrelated code inside it
right now.  But if Spoon makes the file trivial, then we can
probably just keep a single TOC document.

> How is the section-tree view handled in the New World Order?

At the moment, the thought is to have this:

GtkTreeModel* yelp_document_get_sections (YelpDocument *document);
(Continue reading)

Permalink | Reply | 0 comments |
headers
Shaun McCance | 19 Apr 2007 00:02
Picon
Gravatar

Documentation Team Meetings

I've lapsed on the documentation team meetings, but we
clearly have important things to discuss.  So we will
have another set of meetings this Sunday, April 22nd.

As before, the writers meeting will be at 17:00 UTC,
and the hackers meeting will be at 18:00 UTC.  It all
takes place in the #docs channel on irc.gnome.org.

The hackers meeting will focus primarily on the current
efforts on library.gnome.org.  Members of the web team
are invited to join in for that.  We will also discuss
our two SoC projects if the appropriate people show up.

The writers meeting is currently open.  If there are
any issues you would like discussed, please add them
to the agenda on the wiki page:

http://live.gnome.org/DocumentationProject/DocTeamMeetings

See you Sunday.

--
Shaun
Permalink | Reply | 0 comments |
headers
Shaun McCance | 20 Apr 2007 04:46
Picon
Gravatar

2007-03-08 Documentation Hackers Meeting

Attending: Shaun, Don, Rodrigo, Goran, Joachim

Mallard
* Current stuff is in gnome-doc-utils/sandbox/mallard
* Joachim asked about scripts to convert from DocBook
  - A first-pass script would be possible, but a human would
    need to tune the results
* Rodrigo asked about KDE adoption
  - KDE has not been approached; Shaun would rather prove the
    project's viability before cross-desktop discussions
* Don and Joachim ask about "Do it" scripts
  - How do we do it?
  - What happens to them on library or on the web?
  - Can't use info links; need to embed them in the right place
    in the document
  - If they're stand-alone blocks, they can be omitted when needed
  - Would we use Dogtail scripts or...?
    - Does Dogtail tie us to Gnome?
    - Dogtail is not in the desktop
    - This requiers accessibility to be enabled
    - Security concerns?

YelpDocument branch
* Shaun actually started working on it again
* Merging will hurt a lot, because trunk has diverged

Spoon
* Needs a version control home
* Rodrigo asked about up caching the document index
* Don will need help with gnome-dod-utils support
(Continue reading)

Permalink | Reply | 0 comments |
headers
Shaun McCance | 20 Apr 2007 16:55
Picon
Gravatar

gnome-doc-utils branched for 2.18

I've just branched gnome-doc-utils for Gnome 2.18.  Stable
old stuff is on the gnome-2-18 branch.  New hotness is on
trunk.

Plans for 2.20:
* Easier color and icon theme stuff
* More visually appealing default rendering
* Improved support for RTL languages
* Various changes to make library.gnome.org work better
* Merging Mallard into the mainline
  ♫ Mallard on the main line ♫ Tell it what you want ♫

I also have plans for substantial changes to the localization
system that will make translators' jobs easier.  But this will
probably be 2.22 material, as it will require work on intltool.

IMPORTANT: The templates and parameters in the DocBook XSLT
will change on trunk.  These changes will not be compatible
with older releases.  This means that if you have custom XSLT
built off of gnome-doc-utils, you may need to make changes to
work with trunk.  It also means that you should not use older
Yelp releases with gnome-doc-utils trunk.

--
Shaun

_______________________________________________
desktop-devel-list mailing list
desktop-devel-list <at> gnome.org
http://mail.gnome.org/mailman/listinfo/desktop-devel-list
(Continue reading)

Permalink | Reply | 1 comment |
headers
Srinidhi B S | 22 Apr 2007 08:47
Picon

Cannot build from trunk :: missing xslt/docbook/html/admon.xsl

Hi,

I'm not able to build gnome-doc-utils from trunk. I get the following message:

make[3]: Entering directory
`/mnt/tmp/srinidhi/src/evolution/gnome-doc-utils/xslt/docbook/html'
make[3]: *** No rule to make target `db2html-admon.xsl', needed by
`all-am'.  Stop.
make[3]: Leaving directory
`/mnt/tmp/srinidhi/src/evolution/gnome-doc-utils/xslt/docbook/html'

Looking at xslt/docbook/html/Makefile.am, there should be a file
called db2html-admon.xsl in the current directory. But this file
doesn't show up even in "svn ls".

Thanks in advance !! :)

Srinidhi.
--

-- 
ASCII ribbon campaign ( )            B S Srinidhi
  - against HTML email  X             http://www.srinidhi-is.in
                     & vCards / \            Bangalore
Permalink | Reply | 0 comments |
headers
Lucas Rocha | 24 Apr 2007 00:36
Picon
Gravatar

GNOME Roadmap - Information Request for yelp

Dear maintainer,

GNOME 2.18 was released ~1 month ago, and we've all started to focus
on the next development cycle. A new roadmapping process has been
proposed[1] to know our short-term and long-term plans. The goal is to
compose a GNOME-wide roadmap for the next stable releases. And we need
your help to do this. It's important that you take a few minutes to
reply to the following questions before May 7.

----

- What are your plans for GNOME 2.20 (next 4 months, before feature and
 UI freezes)?

- What are your plans for GNOME 2.22 (next year)?

- Do you have plans for a future release?

- Do you have any goals from 2.18 that were not achieved? Why?

- Is there something that is really missing in our infrastructure or
 platform that would help you?

- Do you have plans to work on other modules not maintained by you?
 What are they?

- Do you have any GNOME-wide goals suggestions for the next releases?

----
(Continue reading)

Permalink | Reply | 0 comments |
headers
Lucas Rocha | 24 Apr 2007 00:06
Picon
Gravatar

GNOME Roadmap - Information Request for gnome-doc-utils

Dear maintainer,

GNOME 2.18 was released ~1 month ago, and we've all started to focus
on the next development cycle. A new roadmapping process has been
proposed[1] to know our short-term and long-term plans. The goal is to
compose a GNOME-wide roadmap for the next stable releases. And we need
your help to do this. It's important that you take a few minutes to
reply to the following questions before May 7.

----

- What are your plans for GNOME 2.20 (next 4 months, before feature and
 UI freezes)?

- What are your plans for GNOME 2.22 (next year)?

- Do you have plans for a future release?

- Do you have any goals from 2.18 that were not achieved? Why?

- Is there something that is really missing in our infrastructure or
 platform that would help you?

- Do you have plans to work on other modules not maintained by you?
 What are they?

- Do you have any GNOME-wide goals suggestions for the next releases?

----
(Continue reading)

Permalink | Reply | 0 comments |

Gmane