Inhoudsopgave maken

jeemka · Bericht door **jeemka** » 23 maart 2005, 14:54

Met NVU ben ik help-pagina's voor een softwarepakket aan het maken. Even wennen, maar nu kan ik redelijke pagina's maken. Geen toeters en bellen, alleen kop-1,-3,-4, paragrafen, tabellen en een enkele verwijzing. Nu wil ik bovenaan een pagina een inhoudsopgave maken, waarin ik de kop-3 items van de pagina wil laten verschijnen. In de inhoudsopgave komt echter ook alle tekst van de onderliggende paragrafen. Wat doe ik fout of is dit een nog niet uitgekristalliseerde functie?

ByteWarrior · Bericht door **ByteWarrior** » 23 maart 2005, 15:38

Documentatie voor software maak je met Docbook, niet met een WYSIWYG-editor zoals Nvu.

Met Docbook (een op XML gebaseerde taal) kan je snel zeer goede documentatie maken. Daarna worden de inhoudstafels en andere pagina's zelf gegenereerd. Zo hoef je zelf niet zitten knoeien.

Hier, hier en hier lees je er meer over.

Docbook XML kan omgezet worden naar HTML, XHTML, PDF, CHM (Microsoft Help) en nog wat andere formaten.

nirwana · Bericht door **nirwana** » 23 maart 2005, 20:55

ByteWarrior schreef:Documentatie voor software maak je met Docbook, niet met een WYSIWYG-editor zoals Nvu.

Dat bepaalt iedereen natuurlijk voor zichzelf. Er zullen ook mensen zijn die het met een tekstverwerker maken en het vervolgens naar HTML of PDF exporteren. Niet iedereen denkt in HTML/XML/SGML-tags, dus heb je daarvoor een editor nodig waarmee je wel in DocBook documenten kunt opmaken en eenvoudig kunt exporteren naar een gewenst uitvoerformaat zonder dat je lastig wordt gevallen met XML en SGML.

Wel heb ik eens iets gelezen over OpenOffice.org die je als DocBook-editor kunt inzetten. Maar als ik deze beschrijving lees dan denk ik dat je het erg graag moet willen als je dat nu wilt inrichten.
Zie ook:
http://www.zzoss.com/projects/oowdbk/op ... -html.html
http://www.mycgiserver.com/~gpiancastel ... 00069.html
http://www.the-emperor.org/wiki/docbook_editors/

nirwana · Bericht door **nirwana** » 23 maart 2005, 21:16

Ik zal ook even inhoudelijk op de vraag reageren. Ik heb zojuist met Nvu (versie 0.90 - 20050310) een testpagina met inhoudsopgave gemaakt. Ook heb ik die direct met Nvu op MozBrowser gepubliceerd

Bij het genereren van de inhoudsopgave heb ik verder niets speciaals ingesteld. Gewoon dat venster geopend en op Ok geklikt.

Je ziet wel dat ik de indeling in kopjes niet helemaal logisch heb gemaakt. Maar dat geeft Nvu ook netjes aan. Daarom is mijn vraag wat er volgens jou mis gaat bij het invoegen van de inhoudsopgave met Nvu.
Wat had je verwacht ? En wat maakt Nvu ervan ?

Je geeft aan dat er ook tekst van de paragrafen zelf wordt meegenomen. Heb je dan de kopjes van de paragrafen ook goed van de tekst gescheiden ? Je kunt dit controleren door op zo'n kopje te gaan staan en dan te zien wat er in het Opmaak-veld in de werkbalk komt te staan. Hetzelfde kun je bekijken als je een regel naar onderen gaat. Zo kun je zien waar een bepaalde opmaak begint en waar deze eindigt.

Als je overschakelt naar de Nvu-weergave met HTML-Tags dan kun je ook zien waar een bepaalde opmaak begint en waar deze eindigt.

Dan nog een tip: je kunt ook de statusbalk van Nvu hier erg handig voor gebruiken. Als je namelijk op ergens in de pagina gaat staan met de cursor dan zie je onderin de statusbalk welke HTML-tags daar van toepassing zijn. Eindigt dat bijvoorbeeld met een <p> klik dan eens op die <p> op de statusbalk. Daarmee wordt die alinea geselecteerd.
Als daar achteraan een <h1> staat dan kun je daar ook op klikken. Daarmee wordt het gedeelte geselecteerd dat op die plaats als Kop1 is opgemaakt (en wat dus in de inhoudsopgave wordt meegenomen).

jeemka · Bericht door **jeemka** » 23 maart 2005, 22:48

Beste Martijn,

Docbook lijkt me prima om in een later stadium de documentatie in te hijsen. Ik heb al wat naar help/documentatiesystemen gezocht. Ik zit nu echter in de situatie dat er al een flink aantal documentatiebestanden zijn, met Frontpage in een simpele html structuur gemaakt. Met Nvu ben ik die nu aan het verbeteren, zowel qua inhoud als qua wegwerken van Frontpage-troep. Dat lukt heel aardig, ik begin te wennen aan de eigen(aardig)heden van Nvu.
Bedankt voor je tips over de inhoudsopgave, daar kan ik mee voort.

Ik hanteer nu de methode om de titel van de pagina bovenaan in Kop1 te zetten, daaronder Kopjes3 en een enkel Kopje4. Onder de Kop1 zou ik dan graag een inhoudsopgave van Kopjes3 en Kopjes4 krijgen. Dit ga ik binnenkort uitvogelen. Nu zijn er echter een paar dagen andere dingen te doen, pas na Pasen kan ik weer met dit werk verder. Tot zover bedankt!

Eén van de pagina's die ik al af heb is te zien op http://www.deviant.nl/help/htdreserve.html.

Groet, Jaap.

ByteWarrior · Bericht door **ByteWarrior** » 24 maart 2005, 20:24

nirwana schreef:
ByteWarrior schreef:Documentatie voor software maak je met Docbook, niet met een WYSIWYG-editor zoals Nvu.
Dat bepaalt iedereen natuurlijk voor zichzelf. Er zullen ook mensen zijn die het met een tekstverwerker maken en het vervolgens naar HTML of PDF exporteren. Niet iedereen denkt in HTML/XML/SGML-tags, dus heb je daarvoor een editor nodig waarmee je wel in DocBook documenten kunt opmaken en eenvoudig kunt exporteren naar een gewenst uitvoerformaat zonder dat je lastig wordt gevallen met XML en SGML.

Je hebt gelijk, Martijn. Niet iedereen kan goed overweg met het typen van tags. Soms ga ik daar misschien te snel van uit.

Ik heb echter ondertussen ook al wat documentatie geschreven en ik vind dat Docbook 'the way to go' is. Het is snel en efficiënt. Misschien wel een leercurve, maar afhankelijk van de ingewikkeldheid van je documentatie kan die leercurve lang of kort zijn...

Iedereen mag best gewoon documentatie in HTML (WYSIWYG dan) maken, maar Docbook is een excellent alternatief.

jeemka · Bericht door **jeemka** » 24 maart 2005, 21:08

Wat betreft het gebruik van tags in een document: daar ben ik een groot voorstander van. Een kleine 20 jaar geleden deed ik een onderzoek bij een grote landelijke organisatie die op een traditionele manier handboeken vanuit een centraal punt over het land verspreidde. Toen bleek al, dat je de redactie- en uitgeeffunctie prima kan scheiden door de redacteuren een beknopte set tags te geven, zodat zij zich verder met inhoud kunnen bezighouden. De uitgeeffunctie kan dan die tekst door een 'processor' halen en zo op diverse media publiceren. Toen is daar gekozen voor een subset van Latex, een prachtige opmaaktaal.

Iemand heeft helaas een derivaat van een SGML gemaakt: HTML waarin opmaak en inhoud lekker door elkaar lopen. Gelukkig is de ontwikkeling van pure opmaaktalen doorgegaan. Nu moet ik mij pragmatisch tot simpele HTML beperken, maar Docbook ga ik zeker als hoop voor de toekomst bestuderen. Intussen probeer ik mijn documentatie in HTML zo gestructureerd mogelijk te houden, zodat een conversie naar Docbook eenvoudig moet zijn.

Groet, Jaap.

jeemka · Bericht door **jeemka** » 20 april 2005, 13:33

NVU 1.0PR geeft nu probleemloos een keurige inhoudsopgave zoals ik hem wil hebben!