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] 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
Re: [documentation-dev] wikidoc: header hierarchy
Nino Novak wrote: AFAIK h1-level headers are obsolete for wiki articles (at least in wikipedia). In the (english) documentation (WG2) h1 is used nevertheless, at least in some articles I read so far. The MediaWiki export filter output also uses h1 as top level. Bug or intention? I can't speak for the MediaWiki export filter... a question on that should go back to the devs working on it H1 is still valid MediaWiki syntax, so it can still be used even if major MediaWiki installs are trying to phase it out. Generally speaking, the specific Wiki docs I work on do not have H1... all start at H2. 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: AFAIK h1-level headers are obsolete for wiki articles (at least in wikipedia). In the (english) documentation (WG2) h1 is used nevertheless, at least in some articles I read so far. The MediaWiki export filter output also uses h1 as top level. Bug or intention? The English user guides with H1 in some articles were done long before I learned anything about how to do wiki articles properly. Some of them were done using a set of macros that came before the mediawiki export filter that is now in OOo. Mostly I try to put anything starting with H1 on a new wiki page (so it becomes the page title, not a heading on the page), 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. --Jean - 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 12:13, Martina Waller wrote: Clayton schrieb: Nino Novak wrote: [...] H1 is still valid MediaWiki syntax, so it can still be used even if major MediaWiki installs are trying to phase it out. Generally speaking, the specific Wiki docs I work on do not have H1... all start at H2. C. I remember that this question came up in another mail group but I cannot find the thread anymore. I know there are docs starting with H1 but they shouldn't. If you look at the styles page with wiki style examples at http://wiki.services.openoffice.org/wiki/Documentation/Dashboard/Styl es you see that the first heading level mentioned is = = heading = = with correponds to H2. AFAIR the rationale was/is header hierarchy: page title = h1 page content = h2..h6 if h1 header is used for content, you loose this hierarchy. In page transclusion or wikibook generation, this should confuse the toc of the transcluding page (never tested it). For me, it seems quite natural to keep the hierarchy this way - but it's not intuitive to have to know it when editing wiki pages. 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
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. 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. ;-) All of this would be done better (I hope) if more people were involved, especially people who are good at noticing details. (I'm not.) --Jean - 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
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. So far it's still highly experimental - yet it's producing a reasonably good document (around 1200 pages and growing...) The problems I'm running into with applying the template and having it just work come from 2 sources... one I can directly change.. the Wiki source being laid out correctly, consistently, etc, and using the right heading levels. 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
