Sorry about the late reply. I didn't check my work email over the weekend.
I m going to read a large part of the DevGuide Wiki. Right at the beginning I
noticed, that this DevGuide needs some updates and maybe reformatting. It
would be easy for me to add some changes to the document here and there while
reading it.
Excellent!
Some history on the Wiki doc may help here. The Developer's Guide was
ported (by me) to the Wiki direct, line by line from the OOo2.x. No
significant edits to the actual content were made. I made a best guess
at the time for layout and where to break things into pages and
sections. This means that in some places, the breakdown might not be
the most logical... or could be combined/split again to improve
readability. If we need to shuffle pages/sections around, that's fine.
Just raise it here on the mailing list first for major structural changes.
Any tooling or scripting using the API is done on the page level, not on
lower level content. The WikiBot does not care about page structure
either. The limits/restrictions we have to think about is possible
external linking if we clump pages together, and simple readability (eg
long pages vs short pages etc.).
(1) The Getting Started section describes how to use the NetBeans IDE. I
already dared to add a corresponding description about the Eclipse IDE.
That's fine. If you want to discuss actual content of the examples,
best to discuss on the d...@api.openoffice.org with the API guys.
(2) The files of a standard installation of OOo 3.0 / OOo SDK 3.0 are found at
different locations than those mentioned in the DevGuide. I changed that
already as well.
Correct them as you bump into them. :-)
(3) All headings in the DevGuide start at level 3, i.e., they are given as
=== Heading ===. The headings of other documents of the OOo Wiki start with
level 1 or 2, respectively . I think the text is much easier to read if the
headings start out at level 1. I didn't find any recommendations about
headings in the style guide.
Again, this comes from the initial porting of the document from Writer
to Wiki. The general structure is:
Article Title = Book Heading 1
=== Wiki H3 === = Book Heading 2
The Wiki H1 ( = Wiki H1 = ) should be avoided (for now). There is
another discussion we recently had here regarding the Wiki H1 level and
some possible issues it may create.
=== Wiki H3 === was chosen as the first heading level on a page probably
more for cosmetic reasons than anything. The Wiki H2 level includes a
horizontal line... H3 does not. The other documents (Admin and Basic)
follow this same style.
Should it be changed? Can it be changed? I don't have an issue with
changing it if it makes things more readable. It is a lot of work to go
and change it all... and probably the main reason things have not been
changed. The least painful way (I think) to do this would be to run the
WikiBot over the guide rather than edit every heading by hand.
(4) The Wiki software creates an anchor for every heading with the name of the
heading. So the heading == This is some particular heading == creates an
anchor with the name "This is some particular heading". If someone changes
the text of the heading, he/she breaks all links to this chapter, which is
pretty bad, in particular since the API reference links to the DevGuide. I
didn't find anything about his problem in the Editing:Help or the style
guide. The MediaWiki suggests to add an anchor to every heading, so one may
change the text of headings and anchors separately. Some Wikis even offer an
{{Anchor}} and an {{Anchors}} template.
How do you think about this problem?
I hadn't considered this issue. This is not a problem when you link to
the page itself, but links to subheadings within an article can be a
problem if the heading is changed. At this point though, the Wiki is
supposed to link to the start of the article/page instead of to a
subsection of that same page.
Is there an extension you know of to manage this? I can go poke around
and see if I can dig up an anchor extension. Better to make sure it's
always working rather than rely on the fallback top-of-article that the
Wiki provides.
(5) The DevGuide mentions different example programs, e.g.,
FirstConnection.java. I cannot find these example programs anywhere. The
DevGuide only shows some excerpts. Where are these example programs? I think,
one should include complete and runnable programs into the DevGuide. Are
there any guidelines about how to do this -- or why this is verboten?
This one should probably be taken up on the d...@api.openoffice.org
mailing list.. I'd like to see Jürgen Schmidt's comments on this before
we make any changes. On the technical side, there is nothing preventing
us from including the full example text as attachments or in-line in the
document.
(6) One can also find a version of the DevGuide at the link
http://api.openoffice.org/docs/DevelopersGuide/DevelopersGuide.xhtml
How is this document related to the Wiki? The DevGuide on api.openoffice.org
contains links to the example programs (see point 5 above), but they are
broken.
This is the source for the original Wiki release of the DevGuide. It is
no longer maintained. It's still valid of course for the
release/version it was released for, but for anything newer... the Wiki
is leading, and will continue to be leading. The Wiki is the source as
well for future ODT and PDF releases of this Guide - something I'm
working on right now, and rather late with publishing. Alpha versions
of this effort can be found here:
http://wiki.services.openoffice.org/wiki/Documentation/Wiki_Books
C.
--
Clayton Cornell ccorn...@openoffice.org
OpenOffice.org Documentation Project co-lead
StarOffice - Sun Microsystems, Inc. - Hamburg, Germany
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org
For additional commands, e-mail: dev-h...@documentation.openoffice.org
