CREANDO DOCUMENTACIN TCNICA CON DOCBOOK

T.S.U. Leonardo Caballero

Grupo de Usuaros Lnu! M"rda # GULMER
$eb S%e& '%%p&(())).*ul+er.or*.,e(
Lnu! User - ./0123 ( IRC User& +a4ross
E#+al& leonardo4aballero5*+al.4o+
$eb S%e& '%%p&((l4aballero.26.4o+(
7al abras 4la,e
Cono4+en%o Lbre8 So9%)are Lbre8 Cul%ura Lbre8 Ele4%r:n4a8 Co+pu%a4:n ; In9or+<%4a.
Do4Boo68 Do4u+en%a4:n es%ru4%urada8 Do4u+en%a4:n de ss%e+as8 SGML8 =ML8 Lnu!.
Resu+en
El presen%e ar%4ulo es un %raba>o de n,es%*a4:n ?ue sur*e +o%,ado por el
n%er"s propo de dar a 4ono4er ?ue es%< de%r<s de %odo el +o,+en%o el pro4eso de
ed4:n8 do4u+en%a4:n ; *enera4:n de d9eren%es 9or+a%os desde Do4Boo6. Se
'a4e la a4lara%ora ?ue es una re4opla4:n de los %e+as +<s +por%an%es ?ue se*@n
nues%ro 4r%ero son los +<s rele,an%es ; ?ue ser<n e!pues%os en es%e %raba>o. El
+s+o aborda el %e+a de do4u+en%a4:n es%ru4%urada en so9%)are lbre8 abordando
+ pr+era e!peren4a 4on es%e ss%e+a de do4u+en%a4:n ?ue nos +o%,: a la
realAa4:n del +s+o ; ?ue +pulsa a +u4'as personas a %raba>ar ba>o la pre+sa
de 4rear do4u+en%a4:n es%ru4%ura en un solo 9or+a%o es%<ndar aber%o ; lbre.
Se*uda+en%e se o9re4e una n%rodu44:n a la do4u+en%a4:n %"4n4a ; por ?ue
usar Do4Boo6. Se*uda+en%e se 'abla de B?ue es Do4Boo6C8 se no+bran dos %pos
de e>e+plos de es%ru4%ura de Do4Boo6& Ar%4ulos ; Lbros8 se plan%ea la 9un4ona el
pro4eso de *enera4:n para Do4Boo6 SGML ; =ML ; se 4%an ?uenes lo usan8 se
des4rben las ,en%a>as ; des,en%a>as de Do4Boo6. Ta+b"n se no+bran los
re?uer+en%os b<s4os para usar Do4Boo6 SGML ( =ML ; se 4%an las re9eren4as
o94ales ; +edos de sopor%e8 4o+o al*unas 4on4lusonesD se ane!a las 9uen%es de
re9eren4as.
Re, s:n
7ro4eso Eers:n del do4u+en%o Au%or Fe4'a
Crea4:n del
ar%4ulo.
1.3 Leonardo Caballero 3G(1H(G11H
Re,s:n del
ar%4ulo
1.3.3 Leonardo Caballero 3I(1H(G11H
7re9a4 o
Jola &D
Desde 'a4e un %e+po KG111 # a4%ualdadL el es%<ndar =ML +e 'a a%raMdo +u4'o +s pr+eras
+ple+en%a4ones 9ueron 4on EBS4r%ps8 AS78 lue*o NS7 ; desde ?ue es%o; en el +o,+en%o del
OConoci mi ento Li bre P1Q 'e apre4ado ?ue =ML se usa en +u4'as 4osas no solo la $eb.
M pr+era ,es 4on Do4Boo6 9ue en una re,s%a espaRola lla+ada OLi nux Free Magazi ne en su
ed4:n N1 P3Q donde e!s%e una se44:n lla+ada ODocbook-ayudaS 4on los s*uen%es %e+as&
Do4u+en%a el so9%)are lbre8 Curso de do4boo6. Lue*o 9or+al+en%e desde 'a4e unos aRos es%o;
%raba>ando para unos pro;e4%os de So9%)are Lbre en Funda4%e M"rda PGQ ; allM se 'a re?uerdo
do4u+en%ar +u4'os pro4esos de ss%e+as para +anuales de usuaros8 de ns%ala4:n8 FAT8 en%re
o%ros. Gra4as a esa e!peren4a ob%enda en + dMa es ?ue les ,o; a 4on%ar 4o+o es Do4Boo6 ;
4o+o se puede usar DL
In%rodu44 :n
Se*@n Beltran Monaterio !"#8 la do4u+en%a4:n %"4n4a en el +undo de las 4o+pu%a4:n es +u;
+por%an%e ;a do4u+en%a pro4esos %ales 4o+o&
Manuales de usuaro.
Lbros8 Tu%orales.
Ensa;os ; ar%M4ulos %"4n4os.
Do4u+en%a4:n de un A7I.
7re*un%as Co+unes.
Dapos%,as8 S%os $eb8 en%re o%ras.
B7or ?u" usar Do4Boo6C
Se*@n $l %royecto &N'M$ !(#8 7ara la 4rea4:n de ar%M4ulos8 lbros8 %u%orales8 en%re o%ros se 'a4e
ne4esaro u%lAar un +edo de do4u+en%a4:n es%<ndar de +anera ?ue la +od94a4:n de los
do4u+en%os 9uen%es sea +as sen4lla al *ual ?ue la *enera4:n de es%os en d9eren%es 9or+a%os
sea un paso %r,al.
La do4u+en%a4:n es%ru4%urada se 4ons%ru;e sobre ele+en%os es%ru4%urados& 4apM%ulos8 se44ones8
p<rra9os8 en%re o%ros. donde los ele+en%os se e%?ue%an 4lara+en%e para ?ue son& re9eren4as8
salda de pro*ra+as8 en%re o%ros. No se da nn*una n9or+a4:n e!plM4%a sobre 4o+o el
do4u+en%o debe ser es4r%o8 sola+en%e sobre su es%ru4%ura ; 4on%endo.
Es%o per+%e el pro4eso au%o+<%4o de los do4u+en%os8 an+ando a los au%ores a ?ue se
4on4en%ren en el 4on%endo de los do4u+en%os ; no en el 4o+o *enerarlos. Ade+<s o9re4e
9a4ldad de +an%en+en%o8 de reapro,e4'a+en%o de re4ursos ; *enera4:n o)) - l i ne.
BTu" es Do4Boo6C
Se*@n $6peda P/Q8PHQ8 Do4Boo6 es un apl4a4:n del es%<ndar SGML(=ML e n4lu;e una DTD
propa ; ?ue se u%lAa de +anera +<s des%a4ada en el <rea de la do4u+en%a4:n %"4n4a8
espe4al+en%e para do4u+en%ar %odo %po de +a%eral ; pro*ra+as n9or+<%4os. E!s%e un
Co+%" T"4n4o de Do4Boo6 en OASIS Kor*nal+en%e *&ML '%enL ?ue +an%ene ; a4%ualAa es%e
es%<ndar. Ade+<s %ene 4as 3I aRos8 n4al+en%e 4o+enA: 4o+o una DTD de SGML
KSGML(DSSSL(DTDL8 pero a par%r de la ,ers:n U e!s%e un e?u,alen%e para =ML K=ML(=SLL. 7or
lo ?ue se re4o+enda =ML ;a ?ue es +<s s+ple de +ane>ar8 ade+<s la ,ers:n I ser<
prn4pal+en%e =ML ; 4o+o sopor%e de ed4:n 'a; un 4re4en%e n@+ero de 'erra+en%as para
%ra%ar =ML +<s no para SGML &K .
Al *unos e> e+pl os
A 4on%nua4:n un e>e+plo s+ple de la es%ru4%ura del do4u+en%o basado en Do4Boo6 SGML(=ML
para un ar%4ulo&
<?xml version="1.0" standalone="no"?>
<!DOCTYPE article P!"#C "$%%O&'#'%%DTD Doc!oo( )*" +,.-%%E."
"/tt01%%222.oasis$o0en.or3%doc4oo(%xml%,.-%doc4oo(x.dtd">
<article lan3="es">
<title>Creando Doc5mentaci6n T7cnica con Doc!oo(<%title>
<articlein8o>
<a5t/or>
<8irstname>"eonardo<%8irstname>
<s5rname>Ca4allero<%s5rname>
<%a5t/or>
<%articlein8o>
<section id="art$intro">
<title>#ntrod5cci6n<%title>
<0ara>
Doc!oo( es 5n a0licaci6n del est9ndar ':*"%)*" e
incl5;e 5na DTD 0ro0ia ; <5e se 5tili=a de manera
m9s destacada en el 9rea de la doc5mentaci6n t7cnica>
es0ecialmente 0ara doc5mentar todo ti0o de material
; 0ro3ramas in8orm9ticos> 0ara ma;or in8ormaci6n cons5ltar a<5?
<5lin(
5rl="/tt01%%222.oasis$o0en.or3%doc4oo(%"%>.
<%0ara>
<%section>
<%article>
O%ro e>e+plo s+ple de la es%ru4%ura del do4u+en%o basado en Do4Boo6 SGML(=ML para un
lbro&
<?xml version="1.0" standalone="no"?>
<!DOCTYPE article P!"#C "$%%O&'#'%%DTD Doc!oo( )*" +,.-%%E."
"/tt01%%222.oasis$o0en.or3%doc4oo(%xml%,.-%doc4oo(x.dtd">
<4oo( lan3="es" id="sim0le@li4ro">
<title>n li4ro m5; sim0le<%title>
<c/a0ter id="ca0it5lo@1">
<title>Ca0it5lo 1<%title>
<0ara>Aola m5ndo!<%0ara>
<0ara>BYo es0ero <5e t5 d?a esta 4ien!<%0ara>
<%c/a0ter>
<c/a0ter id="ca0it5lo @-">
<title>Ca0it5lo -<%title>
<0ara>Aola otra ves> m5ndo!<%0ara>
<%c/a0ter>
<%4oo(>
BC:+o 9un4ona Do4Boo6C
En la s*uen%e *r<94a se lus%ra el 9lu>o de pro4esos por la ?ue un au%or de do4u+en%a4:n *enere
desde Do4Boo6 SGML8 9or+a%os 4o+o JTML8 RTF8 7DF8 7S ; o%ros +<s. D4'a lus%ra4:n 9ue
realAada por Is+ael Olea para su 4on9eren4a *&ML+,ML %ara autore de documentaci -n.
F*ura 3. En%orno Do4boo6 SGML en Lnu!
En la s*uen%e *r<94a se lus%ra el 9lu>o de pro4esos por la ?ue un au%or de do4u+en%a4:n *enere
desde Do4Boo6 =ML8 9or+a%os 4o+o JTML8 7DF8 7S ; o%ros +<s. D4'a lus%ra4:n 9ue realAada
por Jard; Bel%ran Monas%eros para su 4on9eren4a Creando Documentaci -n ./cni ca con
DocBook.
F*ura G. En%orno Do4boo6 =ML
BTuenes usan Do4Boo6C
E!s%en +u4'os usuaros de Do4Boo6 alrededor del +undoD a 4on%nua4:n 4%o al*unos
pro;e4%os n%erna4onales& Consul%ores ; au%ores de do4u+en%a4:n lbre8 E+presas del se4%or IT
%ales 4o+o& IBM8 SunD Ta+b"n +u4'as ds%rbu4ones de GNU(Lnu!8 4o+o& Deban8 Red Ja%8
Fedora8 Suse8 Gen%oo8 FreeBSD8 LFS8 en%re o%rosD pro;e4%os de do4u+en%a4:n de So9%)are
Lbre(Aber%o %ales 4o+o& GNOME8 KDE8 7J78 Lnu! Do4u+en%a%on 7ro;e4%8 7J78 OVRell;8 en%re
o%ros. ; en EeneAuela 4onoA4o de buena 9uen%e el 4aso de Funda4%e M"rda PGQ 4on pro;e4%os
4o+o SAID P.Q.
Es%e 4aso 9ue la pr+era ,eA ?ue se uso es%e ss%e+a de do4u+en%a4:n en Funda4%e M"rda para
el dseRo de los +anuales de usuaro ; ns%ala4:n de 4ada +odulo del SAID usando Do4Boo6
4on SGML(DSSSL(DTD se *eneraron los +anuales en d9eren%es 9or+a%os 4o+o 7DF8 JTML8 7S8
en%re o%ros. Ta+b"n 'an lo*rado pro*ra+ar %areas 4on OMa6e9leS para a*lAar la labor de
*enera4:n de los +s+os.
Een%a> as
E!s%en ,aras ,en%a>as ?ue a 4on%nua4:n des4rbr"&
Se puede *enerar ,aros 9or+a%os desde una sola 9uen%e.
Los do4u+en%os es%ru4%urados abren la posbldad de 4rear ss%e+as a,anAados de
b@s?ueda de n9or+a4:n.
La presen%a4:n separada del 4on%endo K; del pro4ed+en%oL8 no es%a l*ado a una
+ple+en%a4:n 4on4re%a KCMSL.
Se puede *enerar o) )l i ne de las p<*nas Kn4luso en o%ro ordenadorL.
7er+%e %odo %po de %rans9or+a4ones del 4on%endo por E>e+plo& o9us4ar dre44ones de
4orreo ele4%r:n4o8 en%re o%ras.
Des,en%a> as
E!s%en ,aras des,en%a>as ?ue a 4on%nua4:n des4rbr"&
De+asadas +ar4as =ML(SGML.
In4al+en%e su aprendAa>e es len%o para ?uenes nun4a usaron Wlen*ua>es de +ar4asX.
Al*unas 'erra+en%as lbres no son su94en%e +aduras para 4er%os usos KE>. Ed%or =ML8
Con,er%r =ML FO a 7DFL.
Earas 'erra+en%as +aduras son solo para $ndo)s ; no son lbres.
Re?uer + en%os B<s 4os
7ara la ed4:n ; *enera4:n desde Do4Boo6 SGML ne4es%a 4o+o +Mn+o ns%alado los
re?uer+en%os&
Un ed%or de %e!%o o ed%or SGML(=ML.
Do4Boo6 ns%alado en su ss%e+a.
El DTD de Do4Boo6 SGML.
Jo>as de es%lo DSSSL Do4Boo6.
Un pro4esador DSSSL.
7or e>e+plo OpenNade.
Un pro4esador de 9or+a%o +pr+ble Ks ?uere 7DFL.
7or e>e+plo NadeTe=.
7ara la ed4:n ; *enera4:n desde Do4Boo6 =ML ne4es%a 4o+o +Mn+o ns%alado los
re?uer+en%os&
Un ed%or de %e!%o o ed%or =ML.
Do4Boo6 ns%alado en su ss%e+a.
El DTD de Do4Boo6 =ML.
Jo>as de es%lo =SLT Do4Boo6.
Un pro4esador =SLT.
7or e>e+plo !sl%pro4.
Un pro4esador FO Ks ?uere 7DFL.
7or e>e+plo Apa4'e FO7.
BM<s do4u+en%a4:n o sopor%eC
E!s%en do4u+en%a4:n o94al8 el +anual de re9eren4a se lla+a DocBook0 .1e De)initi2e &uide P2Q.
Ade+<s e!s%en +anuales en espaRol en la s*uen%e dre44:n ele4%r:n4a P0Q. Un buen s%o para
'a4er pre*un%as Li ta de correo en e%a3ol %ara ayuda y ai tenci a al uo de l a D.D de
com%oi ci -n de documento t/cni co DocBook P33Q dspues%a a 4olaborar en%re s 4on un
espMr%u al%rus%a n4luso a4larando dudas %"4n4as.
Con4lus ones
Do4Boo6 lla+a la a%en4:n por dos 4ualdades +por%an%es& Se puede *enerar ,aros 9or+a%os
desde una sola 9uen%e ; los do4u+en%os es%ru4%urados abren la posbldad de 4rear ss%e+as
a,anAados de b@s?ueda de n9or+a4:n. Cada dMa las 'erra+en%as en GNU(Lnu! +aduran +<s ;
su adop4:n se e!%ende 4ada dMa +<s.
Es%o es una n%rodu44:n *eneral de Do4Boo68 les n,%o a ?ue 4onoA4an +<s ; pon*an en
pra4%4as es%os ti%8 usen los +anuales de re9eren4a P2Q ; los %u%orales en espaRol P0Q.
Y en l a pr:! +a Z
En la pr:!+a en%re*a e!pl4ar" sobre $di tore de DocBook8 ; asM lo*rar una produ4%,dad en
el pro4edo de do4u+en%a4:n 4on Do4Boo6.
Re9eren4 as
K1L '%%p&((es.)6peda.or*()6(Cono4+en%o[Lbre
K3L '%%p&(())).6ernelprodu6%on.4o+(ne)9leG0.'%+
KGL '%%p&(())).9unda4%e#+erda.*ob.,e(
K.L '%%p&((sad.9unda4%e#+erda.*ob.,e(
KUL '%%p&(())).'ard;.4o+.bo(9les(se+naros(do4Boo6#%u%oral#4on*reso.pd9
KIL '%%p&((lbros.es.*no+e.or*(lbro*no+e(lbro*no+e(lbro*no+e(40/2G.'%+l
K/L '%%p&((es.)6peda.or*()6(Do4Boo6
KHL '%%p&((en.)6peda.or*()6(Do4Boo6
K2L '%%p&(())).do4boo6.or*(%d*(nde!.'%+l
K0L '%%p&(()6.do4boo6.or*(%op4(Do4Boo6Tu%orals
K31L '%%ps&((ls%as.'spalnu!.es(+al+an(ls%n9o(do4boo6#a;uda