Editarea cu WikiText pentru LDP - HOWTO

Author: David Merrill

Traducerea în limba română: Laurenţiu Buzdugan

2002-01-23

Istoricul versiunilor
Versiune 1.02003-09-25lb
Prima versiune a traducerii în limba română a versiunii v1.1 (2002-01-28) în limba engleză.

Rezumat

Acest HOWTO explică cum se foloseşte formatul de editare LDP WikiText pentru a crea documente DocBook pentru LDP.


Cuprins

1. Chestiuni legale
2. Introducere
3. Ce este Wiki?
4. De ce aş dori să folosesc WikiText?
5. Cum funcţionează?
5.1. Secţiuni
5.2. Liste
5.2.1. Liste numerotate
5.2.2. Liste cu buline
5.3. Legături
5.4. Nume de fişiere
5.5. Accentuare
5.6. Seturi Q&A (QandASets)
5.7. Alte marcaje
6. Ce se întâmplă cu Meta-Data?
7. Unde este? Pot obţine acces?
8. Concluzie

1. Chestiuni legale

Versiunea originală în limba engleză este distribuită cu următorul mesaj:

“This document is copyright © 2002, David Merrill, and is available under the term of the GNU Free Documentation License, with no invariant sections, no front-cover matter and no back-cover matter. ”

Versiunea în limba română a acestui document este Copyright © 2003 de Laurenţiu Buzdugan şi este disponibilă în conformitate cu Licenţa pentru Documentaţie Liberă GNU (GNU FDL), fără secţiuni invariante, fără conţinut pentru copertă faţă şi fără conţinut pentru copertă spate.

2. Introducere

LDP foloseşte formatul DocBook pentru noile noastre documente şi încearcă să convertească şi vechile documente în DocBook. Din păcate DocBook este un DTD complex şi foarte larg, astfel că poate fi foarte dificil de folosit. Noi căutăm în permanenţă noi căi de a face acest proces mai uşor, astfel ca mai mulţi oameni să poată ajuta LDP.

Soluţia pe care am găsit-o a fost inspirată de WikiWikiWeb, mulţumită unei sugestii făcute de Martin Wheeler, unul dintre autorii LDP. Eu numesc această soluţie WikiText, pentru că nu este un Wiki adevărat, dar are multe dintre cele mai bune capabilităţi ale unui Wiki adevărat.

3. Ce este Wiki?

Un Wiki este un fel de website unde oricine citeşte situl îl poate şi edita. Deşi LDP nu va implementa acest mod de editare permisivă, ne place modul în care funcţionează editarea Wiki. În loc să trebuiască să învăţaţi marcaje html, introduceţi informaţia d-voastră ca text obişnuit. Software-ul Wiki ia acel text obişnuit şi îl converteşte în html pentru publicare.

În cazul nostru, noi nu convertim în html ci în DocBook. Apoi acel DocBook este introdus în sistemul nostru obişnuit de publicare, ca şi cum l-aţi fi scris direct în DocBook.

Dacă n-aţi folosit vreodată un WikiWikiWeb, vedeţi http://www.wikipedia.com pentru un exemplu bun de Wiki.

Funcţiile obişnuite cum ar fi crearea de legături, liste cu buline, liste numerotate şi titlurile secţiunilor sunt accesibile repede şi uşor. Noi am dorit să oferim acelaşi nivel de uşurinţă autorilor LDP, aşa că am scris un program utilitar care ia un text formatat similar cu cel folosit în Wiki-uri (format pe care noi îl numim WikiText) şi îl combinăm cu meta-data din baza de date LDP pentru a genera DocBook.

4. De ce aş dori să folosesc WikiText?

Iată câteva dintre motive:

  1. Este rapid şi uşor. Nu trebuie să învăţaţi marcaje complicate, doar câteva simple "sugestii" (hints) text.

  2. E puternic. Deşi puteţi edita WikiText fără a folosi deloc DocBook, puteţi de asemenea folosi orice marcaje DocBook în conţinut.

  3. Are versiuni. O istorie completă a versiunilor a ceea ce aţi editat este menţinută în baza de date. Puteţi reveni la o versiune anterioară dacă nu vă place ceva ce aţi făcut. Puteţi face aceasta şi cu cvs, dar este mult mai uşor cu sistemul online.

  4. Facilitează colaborarea. Autorii care lucrează la un document împreună cu alţi autori pot colabora prin WikiText. Da, cvs poate face şi acest lucru, dar din nou WikiText e mai simplu.

  5. E accesibil. Tot ce aveţi nevoie e un navigator de web şi un cont pentru baza de date LDP.

  6. Este WYSIWYG. Există o capabilitate de "Previzualizare", apăsând butonul "Preview" puteţi vedea cum va arăta documentul d-voastră pe situl LDP. Nu există nici o utilitate de rulat, nimic de învăţat, nici un DTD de instalat sau fişiere catalog cu care să vă luptaţi să meargă. Dacă aţi încercat vreodată să faceţi să meargă un sistem DocBook pe maşina d-voastră, veţi aprecia acest motiv! :-)

5. Cum funcţionează?

Am încercat să folosim aceleaşi sugestii text care sunt folosite pe Wikipedia, care provin din UseModWiki. Există câteva diferenţe între diferitele sisteme Wiki, dar cele mai multe dintre acestea sunt similare cu cel implementat de noi şi s-au dovedit a fi practice şi utile.

O linie goală separă paragrafele şi există alte sugestii pentru crearea secţiunilor, listelor, legăturilor, numelor de fişiere, etc.

5.1. Secţiuni

=Introducere|intro=

crează o nouă secţiune pe primul nivel (top level). Vedeţi caracterul "|" (pipe) urmat de "intro"? Multe sugestii furnizează un id (identificator), iar acesta este modul în care îl specificaţi. Pentru secţiuni, id-ul va deveni numele fişierului de ieşire (intro.html în acest exemplu) sau numele "marcajului" html folosit pentru legături în interiorul documentului.

==Cum funcţionează|cum-funcţionează==

crează o secţiune pe al doilea nivel, iar

===De ce l-aş folosi?|de-ce===

crează o secţiune pe al treilea nivel.

5.2. Liste

5.2.1. Liste numerotate

# unu
# doi
# trei
/#

Prefixul "#" sugerează crearea unei liste numerotate. Lista numerotată continuă până la sfârşitul secţiunii curente sau până întâlneşte o linie cu "/#", care închide lista. După deschiderea unei alte liste "#", numerotarea va începe din nou de la "1".

Iată cum va arăta blocul de deasupra în documentul final:

  1. unu

  2. doi

  3. trei

5.2.2. Liste cu buline

Listele cu buline funcţioneză aproape identic, cu excepţia sugestiei "*" şi nu trebuie să vă îngrijoraţi de chestiunea renumerotării:

* unu
* doi
* trei
/*

Iată cum va apărea blocul de deasupra:

  • unu

  • doi

  • trei

5.3. Legături

Folosiţi parantezele pătrate pentru a identifica legăturile, astfel:

[[http://www.linuxdoc.org|Linux DocumentationProject]].

În acest caz textul de după caracterul "|" (pipe) nu este un id ci "titlul" legăturii.

Există două nume de domenii (namespaces) pe care le puteţi folosi pe lângă cele standard "http" şi "mailto:" cu care sunteţi probabil familiar. Primul este "ldp:". Vedeţi următoarea legătură:

[[ldp:Distributions-HOWTO]]

Când folosiţi numele de domeniu "ldp:", WikiText va căuta documentul numit în baza de date LDP şi va genera o legătură către aceasta.

Notă: Încă lucrăm la introducerea "numelui" corect în toate înregistrările bazei noastre de date, aşa că numai câteva funcţionează. Dar nu vă îngrijoraţi. Spuneţi-ne dacă doriţi să folosiţi o legătură care nu este încă corectă şi o reparăm imediat.

Al doilea nume de domeniu special este "wiki". Acesta va genera o legătură către articolul respectiv de la Wikipedia, un proiect pentru o enciclopedie open source. Sperăm să reflectăm (mirror) câteva dintre cele mai potrivite articole din Wikipedia direct la LDP. Wikipedia are o mulţime de articole superbe despre subiecte referitoare la computere ce nu sunt genul de informaţie pe care o furnizăm noi la LDP, dar care ar complementa foarte bine documentele noastre. De exemplu, există articole referitoare la memoria virtuală, sisteme de operare, etc. Deocamdată, legătura d-voastră va fi creată către situl Wikipedia. În cele din urmă aceasta va referi o oglindă pe situl nostru dar cu o legătură către situl "real".

Următoarele legături merg către articolele numite "Operating system" şi "Linux kernel" de la Wikipedia:

[[wiki: Operating system]]
[[wiki: Linux kernel]]

Wikipedia este o resursă nemaipomenită pentru toţi utilizatorii Internetului (Netizens). Atât software-ul pe care îl folosesc ei cât şi conţinutul lor sunt open source.

5.4. Nume de fişiere

Puteţi indica numele de fişiere punându-le între paranteze pătrate duble, ca şi legăturile http şi celelalte. Sau, puteţi specifica numele de domeniu "file":

[[/etc/apache/httpd.conf]]
[[file:/etc/apache/httpd.conf]]

În ambele cazuri, acesta va fi afişat ca /etc/apache/httpd.conf.

5.5. Accentuare

Puteţi accentua anumite cuvinte punându-le între trei (3) ghilimele simple, astfel:

'''Wow!'''

Acesta va fi afişat ca: Wow!

5.6. Seturi Q&A (QandASets)

Puteţi crea seturi de întrebări (Q:) şi răspunsuri (A:) dacă scrieţi un FAQ, sau dacă aveţi o secţiune FAQ în documentul d-voastră. Pur şi simplu puneţi "Q:" şi "A:" ca primele caractere pe o linie nouă şi marcajele QandAset vor fi create automat.

Q: Dar dacă doriţi un marcaj DocBook ce nu e suportat de WikiText?

A: Mu.

Şi iată cum este afişat acest exemplu. Observaţi că o listă de întrebări apare chiar înainte de prima întrebare. Aceasta arată puţin stupid în acest exemplu, întrucât avem o singură întrebare şi aceasta e repetată de două ori. Dar dacă lucraţi la un Linux-FAQ, este foarte util.

Q: Dar dacă doriţi un marcaj DocBook ce nu e suportat de WikiText?
Q:

Dar dacă doriţi un marcaj DocBook ce nu e suportat de WikiText?

A:

Mu. Vedeţi secţiunea următoare.

5.7. Alte marcaje

Nu există nici o structură DocBook care nu e suportată de WikiText. De ce? Pentru că dacă nu există nici un WikiText pentru aceasta, puteţi pune marcajele respective direct în document şi vor merge.

Există câteva marcaje "speciale" care nu sunt DocBook inline, ci structuri de secţiuni, printre acestea "programlisting" şi "screen". Ar trebui să reţineţi că nici una din funcţiile WikiText nu funcţionează în interiorul acestor marcaje. Că doar nu doriţi ca liniile de comentariu să fie convertite în liste numerotate, nu?

# acesta este un comentariu
# şi NU o listă numerotată!

6. Ce se întâmplă cu Meta-Data?

D-voastră nu trebuie să introduceţi nici o informaţie gen articleheader sau articleinfo în document. Această informaţie este extrasă direct din baza de date. Mergeţi la pagina de editare a documentului şi introduceţi informaţia necesară acolo.

7. Unde este? Pot obţine acces?

Orice autor LDP este binevenit să folosească WikiText. Acesta este accesibil la baza de date LDP, http://db.linuxdoc.org. Trebuie să aveţi un cont pentru baza de date. Dacă încă nu aveţi un cont, puteţi să-mi cereţi unul prin email. Trimiteţi-mi numele d-voastră complet (aşa cum apare pe documente), numele de utilizator şi parola şi eu îl voi configura pentru d-voastră, probabil în aceeaşi zi.

Odată sunteţi logat la baza de date, faceţi clic pe "My Documents". Dacă nu vedeţi o listă (doar) cu documentele d-voastră, am greşit eu ceva :-)

Faceţi clic pe documentul pe care doriţi să-l editaţi. Veţi vedea o pagină care arată meta-data pe care o avem pentru document. Pe aceeaşi pagină este şi o legătură către WikiEdit. Urmaţi-o şi sunteţi gata de lucru.

Faceţi clic pe "Preview" pentru a vedea cum va apare documentul d-voastră pe LDP (atât că va fi afişată într-o singură pagină).

Faceţi clic pe "DocBook" pentru a vedea codul DocBook pe care WikiText l-a generat din textul d-voastră.

Faceţi clic pe "Save" pentru a salva schimbările în baza de date. Puteţi adăuga un comentariu pentru referinţă.

Faceţi clic pe "Version History" pentru a vedea o înregistrare a tuturor schimbărilor pe care le-aţi făcut documentului.

8. Concluzie

Sperăm că veţi constata că WikiText vă uşurează munca de autor, că vă puteţi acum concentra pe scrierea celei mai bune documentaţii posibile şi că petreceţi mult mai puţin timp încercând să configuraţi utilitarele şi învăţând o sintaxă complicată.

Aş aprecia foarte mult orice sugestii şi observaţii din partea d-voastră, fie aceastea pozitive sau negative (atâta vreme cât sunt constructive, bineînţeles). Îmi puteţi scrie (în limba engleză) la adresa david@lupercalia.net.