Docbook abordare sistem de documentare, sisteme deschise

Înregistrarea conferinței

utilizator de supraveghere pot găsi pe web o mulțime de documente cu același tip de navigare între pagini folosind link-urile Prev, Next, Up, Top, și unul și același instrument poate fi oferite în mai multe formate: în cascadă HTML, un singur HTML, PDF (Figura 1.).

Este clar că documentele în formate diferite sunt generate dintr-o singură sursă. Din ce? Pentru a afla, uita-te la "organe" - în codul HTML:

charset = ISO-8859-1 »>


din HOWTO-uri adăugate la documentația Samba de-a lungul anilor.

Ce este atât de atractiv în privința acestei tehnologii și pentru cine poate fi util? De fapt, pentru că există o mulțime de programe de procesare de text (incepand cu Microsoft Word), desktop publishing (de exemplu, Xerox Ventura Publisher, Adobe PageMaker) și limbaje de markup (unix nroff / troff, TeX / LaTeX, același HTML). DocBook și-a moștenit avantajele din XML:

• simplă limbă de markup asemănătoare HTML;
• separarea clară a conținutului și aspectului, care nu este în HTML;
• Un set puternic de standarde și instrumente de sprijin care permit procesarea textelor (XSLT, XSL-FO, Xpath);
• independența față de producătorii comerciali și standardele acestora, disponibilitatea instrumentelor disponibile în mod gratuit;
• extensibilitate.

În plus, HTML nu este clar formalizat. Desigur, există un standard oficial W3C, dar, în realitate, ambele browsere și Webmasteri utilizează în mare măsură desenele non-standard. Acest lucru face dificilă automatizarea procesării documentelor HTML, pe care nu le puteți face fără, când vine vorba de mediul corporativ.

Datorită suportului pentru XML în DocBook, există o serie de deficiențe inerente în instrumentele HTML. Deci, în DocBook există doar etichete structurale. Există o mulțime de ele (aproximativ 400), dar doar câteva zeci se execută: în loc de

și așa mai departe. Formatul documentului este rigid menținută, de exemplu, fiecare etichetă de deschidere este obligat să se conformeze închidere. În caz contrar, nimeni nu va procesa un astfel de document. În cele din urmă, având o intrare de document bine structurat adaptat pentru procesare automată, primind ieșirea documentului, redactat în stilul corporativ, în HTML, PDF, WinHelp sau alta, este o chestiune de tehnică - în ciuda faptului că există deja o mare parte a instrumentelor, XSL- standard de procesoare.

Simplu și intuitiv.

unelte

Convertoarele sunt un procesor XSLT și scripturi. Ambele sunt disponibile ca parte a distribuției aproape a oricărei versiuni mai mult sau mai puțin moderne a sistemului de operare Linux. Script-uri sunt în mod constant în curs de dezvoltare, de exemplu, în versiunea 1.68 Corecții defecte în index în limba rusă, astfel încât acestea să nu se actualizează imediat prin descărcarea cea mai recentă versiune (docbook.sourceforge.net/projects/xsl) și implementarea arhiva la server.

Pentru a converti documentul sursă la formatul de ieșire, tastați:

$ xsltproc /usr/docbook/xsl-stylesheets/html/chunk.xsl article.xml

- xsltproc - program numit, procesor XSLT (unul din mai multe posibil);

- / usr / docbook / xsl-stylesheets - acesta este locul pe server unde sunt localizate scripturile XSLT;

- html / chunk.xsl - una dintre opțiunile pentru generarea documentului de ieșire;

- articolul.xml este documentul sursă pentru DocBook.

Gata! În directorul curent ar trebui să apară fișiere HTML, una pentru fiecare secțiune a articolului și un cuprins general.

Primul, cel mai simplu nivel de personalizare este alegerea scriptului de pornire. În exemplul anterior este cel al HTML / chunk.xsl - este cea mai solicitate, dar nu singurul. Mai multe oportunități de a controla aspectul documentului de ieșire prevede parametri, care doar chunk.xsl există mai mult de 200. Exemplu: forța punctul culminant într-un fișier separat, prima secțiune a documentației și a specifica codarea documentului de ieșire ferestre-1251 în loc de UTF-8, adoptat în mod implicit:

$ xsltproc - param chunk.first.sections 1
> --stringparam chunker.output.encoding ferestre-1251
> /usr/docbook/xsl-stylesheets/html/chunk.xsl article.xml

Pentru munca reală va dori să stabilească cel puțin o duzină de parametri, dar pentru a face acest lucru prin linia de comandă incomod. Prin urmare, puteți folosi așa-numitul "driver XSL". Ca rezultat al manipulării ne putem asigura că au generat HTML-pagini se vor întâlni pe deplin ideile tale pe estetica si ergonomie, sau pur și simplu se potrivesc stilului dvs. corporative (fig. 2).

Flexibilitatea maximă în utilizarea scripturilor XSL poate fi realizată dacă înlocuiți nu numai valorile parametrilor, ci și codul utilizat pentru a gestiona anumite etichete. De exemplu, dacă nu vă simțiți confortabil cu modul în care este dezvoltat un șablon, pur și simplu îl copiați dintr-un fișier din directorul / usr / docbook / xsl-stylesheets la driverul dvs. și îl manipulați după cum doriți. Șabloanele pe care le veți scrie vor fi blocate de cele importate. În mod similar, puteți schimba nu numai procesarea etichetelor existente, ci și introduceți-vă propria!

Este posibil să existe o situație în care documentul dvs. este corect în ceea ce privește XML, dar nu se va potrivi cu schema DocBook. De exemplu, acesta va avea etichete create de utilizatori. Scenariile XSL se comportă foarte inteligent: textul conținut în interiorul acestor etichete va merge la documentul de ieșire, dar va fi evidențiat în roșu. Acum este timpul să scrieți manualul (xsl: template) pentru eticheta inventată și să-l inserați în driverul dvs. sau, chiar mai bine, să îl importați dintr-un fișier separat.

Formate de ieșire

Conversia de la DocBook la HTML în scripturi standard XSL este aproape perfectă. Nici o problemă cu generarea în ajutorul Windows HTML Help. Scriptul htmlhelp / htmlhelp.xsl creează un set HTML și fișierele de serviciu necesare. După aceea, este lansat hhc.exe compilatorul de ajutor, pe care Microsoft îl distribuie în mod liber, iar ajutorul HTML este generat.

procesoare-FOP comerciale, probabil, cel mai bun de departe este produsul RenderX XEP de la un preț în jurul valorii de $ 300. Acesta este un produs matur și problemele cu limba rusă nu are beneficiul întregii echipe de dezvoltatori vorbitori de limbă rusă. Din păcate, "în afara cutiei" fonturile chirilice din ea nu funcționează și nu există instrucțiuni care să explice într-un mod sensibil cum să le includem. Dar dacă ați ghicit-o, atunci totul funcționează bine, există chiar și liniuțe pentru textul rusesc.

A doua alternativă este conversia intermediară în LaTeX. Scripturile standard XSL nu o acceptă, dar există, de exemplu, db2latex - de asemenea, un pachet de scripturi XSL care pot fi făcute pentru a face ceea ce este necesar. "Din cutie" nu funcționează nici cu litere ruse - trebuie să configurați driverul XSLT. Documentul generat în format LaTeX poate fi convertit în PDF prin comanda pdflatex, care este disponibilă și pe Linux. Apoi, textul rusesc apare, dar la un rezultat satisfăcător este încă departe: există erori în diagramă, în alinierea textului, în marcaje PDF etc. De asemenea, în db2latex atributul morerows nu este suportat - este imposibilă combinarea celulelor pe verticală în tabele. În plus, a devenit clar că pentru a aduce această opțiune în minte nu se poate face fără un studiu aprofundat al TeX / LaTeX.

Nu în ultimul rând sursa problemelor este compania Adobe PDF - dificultăți cu sprijinul limbii ruse sunt aproape toate produsele sale: în Photoshop și în FrameMaker, și Acrobat. Aparent, printre programatorii din Adobe încă nu mai există imigranți din fosta URSS. Iată ce scrie compania despre Adobe Acrobat versiunea 6: "Când se creează fișiere PDF din fișierele HTML, textul tipărit de fonturile chirilic este înlocuit cu simboluri sau goluri incorecte". Cu alte cuvinte, nu funcționează - nu ar trebui!

Ca rezultat, am ajuns la concluzia că singura simplă și care funcționează în mod fiabil varianta de generare PDF în limba rusă - este Acrobat Distiller, care pot include fonturile utilizate în documentul generat, care garantează lectură la orice calculator, nu doar pe ceea ce este echipat cu limba rusă versiunea de Windows.

Pentru un scriitor tehnic

În mod tradițional, documentația a fost în primul rând înțeleasă ca un document tipărit sau o carte. În prezent, documentația este în majoritatea cazurilor necesară atât în ​​format tipărit, cât și în format electronic. Dacă aveți deja un document pentru imprimare, atunci cea mai ușoară cale (și cea universală) de ao face o opțiune electronică este utilizarea Adobe Acrobat Distiller. Veți primi un PDF care poate fi scris pe un CD sau pus pe un site web. Cu toate acestea, PDF-ul nu este nativ la formatul Internet. Documentele dvs. nu vor deveni o parte organică a site-ului și vor irita utilizatorul cu o lungă descărcare, nu vor putea conecta designul standard al site-ului (capace, panouri, servicii), fac dificilă utilizarea legăturilor și căutarea prin site.

Abordarea conceptuală a problemei documentelor DocBook în mai multe formate este cel mai competent: codul sursă, absolut nu legat de formatul de ieșire, și să controleze parametrii programului de generare de documente de ieșire. Într-o implementare practică a generație de document HTML a fost rezolvată, cu PDF-ul nu este încă complet netedă, dar încă problema este rezolvată, de asemenea.

În plus, scriitorul tehnic are nevoie de un serviciu: numerotarea automată a secțiunilor, tabelelor, desenelor, formarea automată a unui cuprins, o listă de cifre, un index alfabetic. Cu toate aceste sarcini, DocBook reușește.

Pentru munca în echipă

Foarte tehnologic, deasupra capului. În același timp, fără a interfera unul cu celălalt, o echipă mare poate lucra pe document.

Conținut, design și structură

Singurul lucru care nu ne-a convins să lucrăm cu DocBook a fost "cozile" SGML, care au apărut în fișierul principal pentru organizarea de linkuri către secțiuni ale documentului. În primul rând, fiecare fișier trebuie menționat de două ori (o dată în definiție, al doilea în plasament); dar în cazul în care există duplicare, apar erori. În al doilea rând, munca cu structuri complexe este organizată necorespunzător. În acest exemplu, doar două fragmente, aceleași documente pentru produsele software pot fi compuse din sute de fragmente cu o adâncime semnificativă a partițiilor cuibăritoare. Există o dorință naturală de a face structura mai vizibilă. Dar cum reflectă cel mai clar structura ierarhică, care este documentul DocBook? Evident, ierarhia directoarelor.

Prin urmare, am implementat următoarea schemă de lucru cu documente ramificate DocBook. Un director separat este creat sub secțiunea de orice nivel. Conținutul secțiunii este plasat în fișierul XML care se află în acest director, iar subdirectoarele sunt create pentru subdirectoarele lor. Fragmentele sunt asamblate automat printr-un program simplu scris pe shell și XSLT. Ordinea corectă a secțiunilor este obținută cu atributul explicit "nr" în etichete. Declarațiile SGML devin inutile.

Acesta din urmă pare a fi important din punctul de vedere al nu atât tehnologiei (în cele din urmă, duplicarea numelor de secțiuni ar putea fi gestionate), câte conceptuale. Dacă nevoia de a separa conținutul și designul este un loc mai mult sau mai puțin obișnuit, atunci am mers mai departe și am reușit să separăm conținutul, designul și structura.

Documentație totală

Strategia XML

DocBook se bazează pe tehnologii XML. Trebuie să vă fie frică dacă aceste tehnologii sunt noi pentru dvs.? În opinia noastră, XML merită fiecare companie IT să își formeze propria strategie de utilizare în legătură cu aceasta. XML - nu este un omagiu pentru modă, deși nu este o salvare a baghetelor. Aceasta este o soluție eficientă pentru o gamă largă de sarcini care până acum au fost dificil de automatizat. Calculatoarele au fost mult timp adaptate la stocarea și prelucrarea, pe de o parte, rigid structurată și datele privind volumul, iar pe de altă parte - date semistructurate, cum ar fi documente de tip text. Puterea XML este că vă permite să organizați și să procesați în mod eficient informații cvasi-structurate: specificații și API; cerințele clientului și scenariile de utilizare; date de testare și scripturi; întrebări frecvente; cursuri de instruire cu prelegeri, exemple și teste. Aceste informații, de regulă, reprezintă o colecție de obiecte cu aceeași structură de nivel superior și descrieri de text la nivelurile inferioare. Spre deosebire de prezentarea unor astfel de informații sub formă de text, XML vă permite să reflectați structura. Pe de altă parte, în comparație cu bazele de date XML are flexibilitate mult mai mare, în timp ce cantitatea de informații este mic și este necesară puterea bazei de date. Există o mulțime de exemple de utilizare cu succes a programului DocBook în sarcini similare. De exemplu, o prelegere este prezentată ca un singur fișier XML, din care sunt generate automat diapozitivele pentru lector; manuale pentru studenți; datele de testare pentru munca de laborator; Sarcini de examinare, întrebări și teste.

Astfel, pentru companiile avansate din punct de vedere tehnologic, DocBook va deveni o completare organică a aplicațiilor XML deja utilizate, iar pentru restul - o bază tehnologică care va facilita implementarea XML.

Anatoli Belychook ([email protected]), Maria Nikolaeva ([email protected]), Nadezhda Matveeva ([email protected]), Stanislav Friedkin ([email protected]) - angajați ai companiei "Console Business" (Moscova) .

DocBook Standard

Varianta materială a DocBook este schemele XML (DTD) și scripturile (DSSSL, XSLT). Acestea sunt distribuite în mod liber: li se permite să fie folosite în orice scop, modificate și reproduse fără restricții și cu permisiune specială. Singurul lucru care este interzis în conformitate cu spiritul comunității Open Source este limitarea altora în utilizarea și distribuirea gratuită a DocBook sau a modificărilor sale.

Standard în populara prezentare DocBook oferi îndrumare [1, 2], care a făcut „selecție“: începând de la aproximativ 400 de tag-uri reduse la 100 cele mai utilizate pe scară largă (și cel mai probabil este mult mai mult decât într-adevăr necesar). Pentru setări XSLT-instrument și parametrii care influențează tipul de ieșire, veți avea nevoie de un ghid [3] și de referință [4].

literatură

1. Norman Walsh, Leonard Muellner. DocBook: Ghidul definitiv (www.docbook.org).
2. Norman Walsh. Documentul simplificat: Ghidul definitiv (www.docbook.org).
3. Bob Stayton. DocBook XSL: Ghidul complet (www.sagehill.net/docbookxsl).
4. Norman Walsh, Bob Stayton, Documentare Jirka Kosek DocBook XSL Stylesheet de referință (docbook.sourceforge.net/release/xsl/ curent / doc / reference.html).

Site-ul DocBook

O nouă aplicație a DocBook este crearea de site-uri Web. Ideea este următoarea: folosind etichetele DocBook, puteți crea un fișier XML pe fiecare pagină de site (etichetă root) plus un fișier XML care conține un cuprins. Apoi, aceste fișiere sunt procesate folosind scripturi XSL, obținând ieșirea dintr-un set de pagini HTML care alcătuiesc site-ul.

În timpul generării, un panou cu un tabel ierarhic al conținutului site-ului este expus automat fiecărei pagini, ale cărui elemente pot fi minimizate și extinse. De asemenea, paginile noi și modificate sunt selectate automat în cuprins. Este demn de remarcat că legăturile dintre paginile site-ului nu sunt făcute cu ajutorul celor cunoscute, ci cu ajutorul etichetei docbook. Acest lucru asigură că toate legăturile interne de pe site-ul rezultat sunt corecte.

Principalul avantaj al acestei tehnologii, cum ar fi DocBook în general, este separarea consecventă a conținutului de design. De exemplu, site-urile www.docbook.org. www.docbook.ru. realizat pe această tehnologie, arăta academic riguros. Dar, folosind metodele standard de instalare a DocBook, puteți schimba radical designul și aspectul site-ului dvs., absolut fără a afecta conținutul acestuia.

Distribuiți materialul împreună cu colegii și prietenii

Invitația lui Howard Reingold ca invitat al următorului număr al "Open Systems" pentru mine are un înțeles special. Sa întâmplat astfel încât suntem bine familiarizați cu el; Am fost implicat în creat

Creșterea exponențială a Web-ului, despre care toată lumea, bineînțeles, a auzit, nu poate continua pentru totdeauna, altfel așteptăm doar colapsul informațional. Volumul informațiilor acumulate este deja atât de mare încât îneacă rezultatele căutării pe Internet.

Programele analitice sunt astăzi principalele mijloace de creștere a eficienței companiilor

Articole similare

• Dezvoltarea documentatiei cu docbook

Trimiteți-le prietenilor: