Re: [documentation-dev] New Math page on the WIki
Clayton wrote: This new Math page was recently added to the Wiki: http://wiki.services.openoffice.org/wiki/Math I added a comment to the Talk page: http://wiki.services.openoffice.org/wiki/Talk:Math Basically.. it's a duplication of something that is already well documented, and I propose that we remove the topic (actually, I'd probably put in a redirect from this Math page to the actual Math documentation) Thoughts? C. +1 for redirect. I left more comments on the Talk page, in hopes the user will see and respond, to improve our indexing. BTW, the link (on the Math page) to plan-b etc., points to a currently free, proposed for-pay support site. This may be a web-ghost: judging by their get-OOo link, which points to V2.3.1, the site is not diligently maintained. That link may belong on the Consultants page (/but:/ more about that on the d...@web list). -- /tj/ - To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org
Re: [documentation-dev] New Math page on the WIki
This new Math page was recently added to the Wiki: http://wiki.services.openoffice.org/wiki/Math I added a comment to the Talk page: http://wiki.services.openoffice.org/wiki/Talk:Math Basically.. it's a duplication of something that is already well documented, and I propose that we remove the topic (actually, I'd probably put in a redirect from this Math page to the actual Math documentation) +1 for redirect. I left more comments on the Talk page, in hopes the user will see and respond, to improve our indexing. BTW, the link (on the Math page) to plan-b etc., points to a currently free, proposed for-pay support site. This may be a web-ghost: judging by their get-OOo link, which points to V2.3.1, the site is not diligently maintained. That link may belong on the Consultants page (/but:/ more about that on the d...@web list). OK, I dropped in the redirect. The original text is still in the original page, just commented out so it's not visible. 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
Re: [documentation-dev] New Math page on the WIki
T. J. Frazier wrote: I left more comments on the Talk page, in hopes the user will see and respond, to improve our indexing. BTW, the link (on the Math page) to plan-b etc., points to a currently free, proposed for-pay support site. This may be a web-ghost: judging by their get-OOo link, which points to V2.3.1, the site is not diligently maintained. That link may belong on the Consultants page (/but:/ more about that on the d...@web list). I had missed the info about plan-b that T.J. mentions, so my comments about linking from our tutorials page may not be so relevant. --Jean - To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org
Re: [documentation-dev] New Math page on the WIki
Jean Hollis Weber wrote: T. J. Frazier wrote: I left more comments on the Talk page, in hopes the user will see and respond, to improve our indexing. BTW, the link (on the Math page) to plan-b etc., points to a currently free, proposed for-pay support site. This may be a web-ghost: judging by their get-OOo link, which points to V2.3.1, the site is not diligently maintained. That link may belong on the Consultants page (/but:/ more about that on the d...@web list). I had missed the info about plan-b that T.J. mentions, so my comments about linking from our tutorials page may not be so relevant. It is an old link... but the Plan-B site is known... at least to me. there is a lot of mention of it on the User Forum for example... and I think... maybe... if my memory serves me correctly, the orginal author of the site is a participant in the OOo Forum. I've linked it for now... we can always remove it in the future if we see the need to. 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
[documentation-dev] Template for ODTs exported from the Wiki
I've been working on cleaning up the Developer's Guide export from the Wiki. This is effectively complete - or as far as I'm going to take it for now. The template I used is a loose mix of the original template used to publish that guide plus elements from the template used for the User Guides. This works, but it could be better... a lot better. There are elements in both templates that are good, and not so good. They do not look the same etc etc. The templates as they are are not effective for using as a template for the Wiki export. I think it would be useful if we worked on a common single template that we can use for all documents that are exported from the Wiki. There are a few considerations for this: - The template needs to be able to map as many of the Collections styles as possible to reduce the manual cleanup of an exported document. This is one of the most important parts of the rework on template. I've done some of this on the template I used for the DevGuide, but it's not done properly (style names are not consistent, not all map to Collections styles, etc). - The template should be clean and professional looking (an objective thing, but if the look/feel is something we can agree on, then we're on track :-) ) In the Template layout, we need to focus on a few things: - Chapter and Appendix title definitions - Tables - these are a bit of a mess in the export - Step numbering/Bullet Lists with appropriate level 1, level 2 etc - Indented paragraphs (in-line with bullet text) - Image layout definition (wrapping/position/anchor point etc) - Widow/orphan settings on all styles - Page size/dimensions (I used A4 for the DevGuide) - Page Margins (left/right... do we assume binding margins or simple margins) and probably a whole lot more. The goal i have in mind is to be able to export a book from the Wiki and import it into the template and only have to do a minimum of post-processing to clean-up the document for publication. Any thoughts or comments on this? Is this achievable? This is something that could probably be added to: http://wiki.services.openoffice.org/wiki/Documentation/Dashboard/Project_Plan as one of the team projects... 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
Re: [documentation-dev] wikidoc: header hierarchy
On Wednesday 02 September 2009 14:42, Jean Hollis Weber wrote: Nino Novak wrote: On Wednesday 02 September 2009 12:39, Jean Hollis Weber wrote: , but sometimes when a section started by a H1 is very short, I keep 2 or 3 of them on one wiki page. Then I have to decide whether to change the other H1s into H2s. (As for me, I'd prefer to put them on different pages if their content is significantly different) Wikipedia has a stub article avoidance policy. In case of (technical) documentation like the UG I don't see any reason for a minimum article length. (just my 2ยข) A lot of what I've done when wiki-fying the English UGs hasn't been well thought out, just done in a rush, hence the inconsistencies. I try to tidy things up when I need to update the content of a wiki page. This discussion is good for that. A propos inconsistencies: Has there been a thought/discussion to use DocBook as master for documentation? Nino - To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org
Re: [documentation-dev] wikidoc: header hierarchy
Clayton wrote: BTW, quite often when I'm tidying up heading levels, I realise that they were poorly chosen in the original ODT, so that needs fixing too. ;-) This goes both ways too as I'm discovering while exporting and applying templates to the Developer's Guide. ... Caution: there's a nasty little bug, http://www.openoffice.org/issues/show_bug.cgi?id=101735 which applies to Writer as well as Calc, involving copying styles. -- /tj/ - To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org
Re: [documentation-dev] Re: DocBook? (was:wikidoc: header hierarchy)
On Friday 04 September 2009 13:46, Jean Hollis Weber wrote: Nino Novak wrote: A propos inconsistencies: Has there been a thought/discussion to use DocBook as master for documentation? I know that OOo is supposed to deal with DocBook files in some way, but I've never understood how that works. Would love to learn more. Can Writer create/edit DocBook files, as a front-end that ordinary mortals can understand? I think that when documenting an office suite with a word processor component, that one should use that word processor component, not some other program. I'm not an expert - to be honest I hoped to meet the experts here ;-) but on the German community mailing list we had a discussion if it makes sense to use the wiki for documentation at all - as this raises the problem of double bookkeeping and of converting documents. A possible solution would be to use a common Master. So my question should have been: does it make sense to consider a general setting with DocBook as master for all documents? I don't know if there are good docbook-odt or docbook-wiki filters but from theory this seems more straightforward than odt-wiki and vice versa. BTW - I don't see any problems in using specialized tools for special goals, think of the issue tracker, pootle, Plone etc. The word processor serves for creating nice documents, the question addressed here is more to generate different output formats from the same content source. Nino - To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org
Re: [documentation-dev] Re: DocBook?
I'm not an expert - to be honest I hoped to meet the experts here ;-) but on the German community mailing list we had a discussion if it makes sense to use the wiki for documentation at all - as this raises the problem of double bookkeeping and of converting documents. A possible solution would be to use a common Master. So my question should have been: does it make sense to consider a general setting with DocBook as master for all documents? I don't know if there are good docbook-odt or docbook-wiki filters but from theory this seems more straightforward than odt-wiki and vice versa. BTW - I don't see any problems in using specialized tools for special goals, think of the issue tracker, pootle, Plone etc. The word processor serves for creating nice documents, the question addressed here is more to generate different output formats from the same content source. One of the big reasons we moved/pushed towards using the Wiki for docs is.. to try and get more community involvement... basically lowering the entry barrier to editing the docs. In at least some documents, this has worked quite well. The Wiki is easy to access, and anyone with a browser can participate. We're just getting those people interested and some are starting to get involved. If we choose to use some other application that must be installed separately or some special OOo configuration requiring plugins and user IDs on certain webservers etc., we will immediately eliminate a segment of contributors, and the doc workload falls back 100% to a very very small team of maybe 3 or 4 people. The example I have is the DevGuide. Before porting it to the Wiki, it was developed in a custom process that required a specific StarOffice version with a special plugin for reading the custom XML sourcefile type. Only someone who had access to this version of StarOffice and could get the plugin could open the source files and edit. This meant basically... 2 people were working on the source and creating the doc. All of the developers had to push their doc changes through these two people. The community had no hope of contributing things like code snippets and making corrections except through raising Issues in the OOoIssue tracker. With this doc in the Wiki, it is subject to a steady stream of edits by developers and community members who keep the doc much more current, and who are adding example code and other helpful bits. One of the issues with working direct in DocBook is that it does require a significant level of expertise, and we're raising that entry bar way up again. Personally I like DocBook, and have written a lot of documentation in raw XML and DocBook... but it's not easy... requires at least some custom tooling in the process etc, and at least some measure of technical skill above your average computer user level - even if you're using a DocBook editor of some sort. If we argue that we can use Writer as a DocBook editor (it is technically possible to export DocBook from Writer), then why bother with DocBook? Do the docs right in ODT. No matter which way we go (Wiki, DocBook, or something else), we will have issues. If we use a CMS of some sort and Writer (TeamDrive and Alfresco, to name two, have OOo plugins so you can access the files direct from OOo), we loose a lot of the simple accessibility that we have in the Wiki. If we use the Wiki, we have difficulty exporting to other formats. The Wiki is definitely not a perfect medium for documenting, but... it does the job reasonably OK in most cases. In a perfect world, I'd like to be able to use OOoWriter to author and edit the docs, save them to webserver (just via save), and be able to automatically/immediately have them rendered into Webpages (as in the way the Wiki works). There is not yet a OOo based Wiki :-) It'd be the best of both worlds. 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
Re: [documentation-dev] Re: DocBook?
If we choose to use some other application that must be installed separately or some special OOo configuration requiring plugins and user IDs on certain webservers etc., we will immediately eliminate a segment of contributors, and the doc workload falls back 100% to a very very small team of maybe 3 or 4 people. Hmmm.. I re-read this and it's not quite sounding the way I wanted :-) Let me try this paragraph again... If we choose to use some other application that must be installed separately (for example a DocBook editor) or some special OOo configuration requiring plugins and a connection to a custom CMS application of some sort, we risk eliminating the segment of contributors we're trying to encourage to participate. I don't know what the balance is between a controlled CMS+XML environment and the Wiki... or some other solution. I'm definitely interested in ideas though... who knows where this discussion could lead :-) 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
Re: [documentation-dev] Re: DocBook?
OOo has very primitive DocBook support. In fact, it uses DocBook 4.1.2 from eons ago. DocBook currently has been at DocBook 5 since the summer of 2007, I believe. I have produced DocBook 4.5 and DocBook 5 EDDs for Adobe FrameMaker, although the DB 5 version is a very small bit incomplete because Norman Walsh (original DocBook person) never completed the DocBook 5 DTD from which a FrameMaker EDD file is created. DocBook 5 was the first to only use a DTD XML source as being nonnormative, as a different normative schema--RELAX NG--was first adopted starting with DocBook 5. Gary Nino Novak wrote: On Friday 04 September 2009 13:46, Jean Hollis Weber wrote: Nino Novak wrote: A propos inconsistencies: Has there been a thought/discussion to use DocBook as master for documentation? I know that OOo is supposed to deal with DocBook files in some way, but I've never understood how that works. Would love to learn more. Can Writer create/edit DocBook files, as a front-end that ordinary mortals can understand? I think that when documenting an office suite with a word processor component, that one should use that word processor component, not some other program. I'm not an expert - to be honest I hoped to meet the experts here ;-) but on the German community mailing list we had a discussion if it makes sense to use the wiki for documentation at all - as this raises the problem of double bookkeeping and of converting documents. A possible solution would be to use a common Master. So my question should have been: does it make sense to consider a general setting with DocBook as master for all documents? I don't know if there are good docbook-odt or docbook-wiki filters but from theory this seems more straightforward than odt-wiki and vice versa. BTW - I don't see any problems in using specialized tools for special goals, think of the issue tracker, pootle, Plone etc. The word processor serves for creating nice documents, the question addressed here is more to generate different output formats from the same content source. Nino - To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org - To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org
Re: [documentation-dev] Re: DocBook?
Hi, On 09/04/09 15:55, Clayton wrote: ... If we argue that we can use Writer as a DocBook editor (it is technically possible to export DocBook from Writer), then why bother with DocBook? Do the docs right in ODT. No matter which way we go (Wiki, DocBook, or something else), we will have issues. If we use a CMS of some sort and Writer (TeamDrive and Alfresco, to name two, have OOo plugins so you can access the files direct from OOo), we loose a lot of the simple accessibility that we have in the Wiki. If we use the Wiki, we have difficulty exporting to other formats. The Wiki is definitely not a perfect medium for documenting, but... it does the job reasonably OK in most cases. In a perfect world, I'd like to be able to use OOoWriter to author and edit the docs, save them to webserver (just via save), and be able to automatically/immediately have them rendered into Webpages (as in the way the Wiki works). There is not yet a OOo based Wiki :-) It'd be the best of both worlds. C. this can be solved by software, so it is not a problem. May be today, but not tomorrow. See the ODF @ WWW project proposed by Kay Ramme some time ago, and watch the screencast at http://odf-at-www.openoffice.org/ And I would be very happy if the Help source files would be available for editing by every interested user. Still a long and winding road to edit and compile the set of Help files. Uwe -- u...@openoffice.org - Technical Writer StarOffice - Sun Microsystems, Inc. - Hamburg, Germany http://documentation.openoffice.org/ http://wiki.services.openoffice.org/wiki/Documentation http://blogs.sun.com/oootnt http://user.services.openoffice.org/en/forum - To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org
Re: [documentation-dev] Re: DocBook?
In a perfect world, I'd like to be able to use OOoWriter to author and edit the docs, save them to webserver (just via save), and be able to automatically/immediately have them rendered into Webpages (as in the way the Wiki works). There is not yet a OOo based Wiki :-) It'd be the best of both worlds. this can be solved by software, so it is not a problem. May be today, but not tomorrow. See the ODF @ WWW project proposed by Kay Ramme some time ago, and watch the screencast at http://odf-at-www.openoffice.org/ Aha.. I knew it was there somewhere, but I couldn't find it.. so I didn't want to try and name it and be caught out without a URL I could point people at :-) Thanks for remembering that one Uwe. And I would be very happy if the Help source files would be available for editing by every interested user. Still a long and winding road to edit and compile the set of Help files. Definitely.. that's another side of this large challenge we face... the Application help. A long and winding road is not descriptive enough for the way the Application help is developed. It would be nice if the Application help was also simplified and easier for the community to work on. It's definitely something to think about. 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
Re: [documentation-dev] wikidoc: header hierarchy
Nino Novak wrote: A propos inconsistencies: Has there been a thought/discussion to use DocBook as master for documentation? Nino - To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org I asked that question some two years ago. Apparently, there was little interest then... BTW, Writer could be used but not the way it has DocBook, as OOo functions as if DocBook development stopped at DocBook 4..1.2--a very primitive version from 18 Dec 2003. Various newer versions were subsequently released*:* 4.2 19 Dec 2003, **4.3 31 Mar 2004, 4.4, 28 Jan 2005, **4.5 03 Oct 2006, and **5.0 06 Feb 2008. But, as I said, OOo's DocBook mindset is mired back at an incomplete 4.1.2 version that is nearing six years old, to boot. Gary - To unsubscribe, e-mail: dev-unsubscr...@documentation.openoffice.org For additional commands, e-mail: dev-h...@documentation.openoffice.org
