1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
|
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML, HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
The FreeBSD Documentation Project
The FreeBSD French Documentation Project
$Id: chapter.sgml,v 1.1 2000-06-12 15:46:44 gioria Exp $
Original revision: 1.8
-->
<chapter id="sgml-primer">
<title>Introduction à SGML</title>
<para>La majorité des documentations du FDP utilisent SGML. Ce chapitre vous
explique ce que cela signifie exactement, comment lire et comprendre le
source de la documentation et décrit la façon d'utiliser le SGML que vous
recontrerez dans la documentation.</para>
<para>Des parties de cette section se sont inspirées du livre de Mark
Galassi, <ulink
url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">“<foreignphrase>Get Going With DocBook</foreignphrase>”</ulink>.</para>
<sect1>
<title>Introduction</title>
<para>Il était autrefois facile de travailler sur des documents
électroniques. Vous n'aviez normalement à connaître que le jeu de
caractères utilisé (ASCII, EBCDIC, ou l'un des nombreux autres) et
c'était à peu près tout. Le texte était du texte, et vous voyiez
vraiment ce que vous obteniez. Pas de sophistication, pas de formatage,
pas d'intelligence.</para>
<para>Cela devint inévitablement insuffisant. Une fois que vous avez du
texte qu'une machine peut lire, vous vous attendez à ce que la machine
puisse l'utiliser et le manipuler intelligemment. Vous aimeriez pouvoir
préciser que certaines phrases sont accentuées, y ajouter un glossaire
ou des hyper-liens. Vous voulez que les noms de fichiers apparaissent
en police “machine à écrire” à l'écran et en italique à
l'impression, et tout un tas d'autres options de présentation
encore.</para>
<para>Il fut un temps où l'on pensait que l'Intelligence Artificielle (IA)
rendrait cela facile. Votre ordinateur pourrait lire le document et
identifier les phrases clés, les noms de fichiers, le texte que
l'utilisateur devait taper, et d'autres encore. Malheureusement, la
réalité est un peu différente, et il faut aider nos ordinateurs à
manipuler intelligemment notre texte.</para>
<para>Plus précisement, il faut les aider à indentifier ce qui est quoi.
Vous et moi, à la vue de :</para>
<blockquote>
<para>Pour effacer <filename>/tmp/foo</filename>, utilisez
&man.rm.1; :</para>
<screen>&prompt.user; <command>rm /tmp/foo</command></screen>
</blockquote>
<para>distinguons facilement ce qui est nom de fichier, commande à
taper, référence aux pages de manuel, et ainsi de suite. Mais
l'ordinateur lui ne le peut pas. Pour cela, Nous avons besoin des
marques.</para>
<para>Le “marquage” est communément qualifié de “valeur
ajoutée” ou “coût augmenté”. Le terme prend ces deux
sens quand il s'applique au texte. La marquage est du texte en
supplément dans le document, distinct par un moyen ou un autre du
contenu du document, de façon à ce que les programmes qui traitent le
document puisse le lire et l'utiliser pour prendre des décisions. Les
éditeurs peuvent masquer le marquage à l'utilisateur, de façon à ce
qu'il ne soit pas perturbé par ces marques.</para>
<para>L'information supplémentaire donnée avec les marques
<emphasis>ajoute de la valeur</emphasis> au document. Le marquage doit
habituellement être manuel - après tout, si les ordinateurs
pouvait analyser suffisamment le texte pour ajouter les marques, il n'y
en aurait alors en fait pas besoin. Cela <emphasis>augment le
coût</emphasis> du document.</para>
<para>L'exemple précédent est codé comme suit dans le présent
document :</para>
<programlisting><![ CDATA [
<para>Pour effacer <filename>/tmp/foo</filename>, utilisez
&man.rm.1;.</para>
<para><command>rm /tmp/foo</command></para>]]></programlisting>
<para>Comme vous pouvez le constater, le marquage est clairement séparé du
contenu.</para>
<para>Bien évidemment, si vous devez utiliser des marques, vous devrez
définir ce que les marques veulent dire et comment elles doivent être
traitées. Il vous faudra un language de marquage auquel vous référer
pour marquer vos documents.</para>
<para>Un seul language de marquage peut bien sûr ne pas suffire. Les
besoins de marquage d'une documentation technique diffèrent énormément
de ceux de recettes de cuisines. ces derniers seront à leur tour
différents de ceux d'un language de marquage pour de la poésie. Vous
avez en fait besoin d'un language qui vous permette de définir ces
autres languages de marquage. Un <emphasis>méta-language de
marquage</emphasis>.</para>
<para>C'est exactement ce qu'est <foreignphrase>Standard Generalised
Markup Language (SGML)</foreignphrase> - Language de Marquage
Standard Généralisé. De nombreux languages de marquage sont écrits en
SGML, dont les deux languages les plus utilisés par le FDP, HTML et
DocBook.</para>
<para>Chaque définition d'un language s'appelle plus exactement une
<foreignphrase>Document Type Definition
(DTD)</foreignphrase> - Définition de Type de Document. La DTD
définit les noms des éléments utilisables, leur ordre d'apparition (et
leur hiérarchie) et les informations qui s'y rapportent. Une DTD est
parfois désignée comme une <emphasis>application</emphasis> de
SGML.</para>
<para id="sgml-primer-validating">Une DTD est une spécification
<emphasis>complète</emphasis> de tous les éléments autorisés, de l'ordre
dans lequel ils doivent être utilisés, quels sont ceux qui sont
obligatoires, quels sont ceux qui sont facultatifs, et ainsi de suite.
Il est alors possible d'écrire un <emphasis>analyseur</emphasis> qui
lise et la DTD et le document qui prétend s'y conformer. L'analyseur
peut alors vérifier si tous les éléments requis sont bien présents dans
l'ordre voulu dans le document et s'il y a des erreurs dans le marquage.
On appelle habituellement cela <quote>valider le
document</quote>.</para>
<note>
<para>Ce traitement ne valide uniquement que le choix des éléments, leur
ordre, et ainsi de suite, se conforme à ce que définit la DTD. Il ne
vérifie <emphasis>pas</emphasis> que vous avez utilisé les marques
<emphasis>appropriées</emphasis> au document. Si vous marquez tous les
noms de fichiers de votre document comme des noms de fonctions,
l'analyseur ne le signalera pas comme une erreur (en supposant, bien
sûr, que votre DTD définisse des éléments pour les noms de fichiers et
de fonctions et qu'ils aient le droit d'apparaître aux mêmes
endroits).</para>
</note>
<para>Il est probable que vos contributions au Projet de Documentation
consiste en documents marqués soit en HTML soit en DocBook, plutôt qu'en
modifications aux DTDs. Pour cette raison, cet ouvrage n'abordera pas la
façon d'écrire une DTD.</para>
</sect1>
<sect1 id="sgml-primer-elements">
<title>Eléments, marques et attributs</title>
<para>Toutes les DTDs écrites en HTML ont des caractéristiques communes.
Ce n'est guère surprenant comme le montre inévitablement la philosophie
qui sous-tend SGML. Une des manifestations les plus visibles de cette
philosophie est la caractérisation en <emphasis>contenu</emphasis> et
<emphasis>éléments</emphasis>.</para>
<para>Votre documentation (que ce soit une seule page Web ou un ouvrage
volumineux) est vue comme étant un contenu. Ce contenu est alors divisé
(et ensuite subdivisé) en éléments. L'objectif de l'ajout de marques est
de nommer et de définir le début et la fin de ces éléments pour
traitement ultérieur.</para>
<para>Considérez par exemple un livre type. Au plus haut niveau, ce livre
lui-même est un élément. Cet élément “livre” contient
évidemment des chapitres, qui peuvent aussi être légitimement considérés
comme des éléments. Chaque chapitre contiendra à son tour des éléments,
tels que des paragraphes, des citations et de notes de bas de page.
Chaque paragraphe peut lui-même contenir encore des éléments, pour
identifier le texte parlé par exemple, ou les noms des personnages de
l'histoire.</para>
<para>Vous pouvez si vous le voulez voir cela comme un
“morcelement” du contenu. A la racine, vous avez un morceau,
le livre. Un niveau en dessous, vous avez plus de morceaux, les
chapitres individuels. Ils sont à leur tour morcelés en pargraphes,
notes de bas de page, noms des personnages, et ainsi de suite.</para>
<para>Remarquez que vous pouvez différencier les éléments sans utiliser
la terminologie SGML. C'est vraiment immédiat. Vous pouvez le faire avec
un surligneur et un livre imprimé, en utilisant des couleurs différentes
pour chaque type d'élément.</para>
<para>Nous n'avons bien sûr pas de surligneur électronique, il nous faut
donc un autre moyen d'indiquer à quel élément appartient chaque morceau
du contenu. Dans les languages écrits avec SGML ,(HTML, DocBook, et
al.), cela se fait avec des <emphasis>marques</emphasis>.</para>
<para>Une marque sert à dire où commence et où finit un élément.
<emphasis>La marque ne fait pas partie de l'élément lui-même</emphasis>.
Comme chaque DTD est habituellement écrite pour marquer des types
d'informations spécifiques, chacune reconnaîtra des éléments différents,
et aura donc des noms différents pour les marques.</para>
<para>Pour un élément appelé <replaceable>nom-de-l'élément</replaceable>,
la marque de début sera normalement
<literal><<replaceable>nom-de-l'élément</replaceable>></literal>.
La marque de fin correspondante sera
<literal></<replaceable>nom-de-l'élément</replaceable>></literal>.</para>
<example>
<title>Utiliser un élément (marques de début et de fin)</title>
<para>HTML dispose d'un élément pour indiquer que le contenu inclus est
un paragraphe, appelé <literal>p</literal>. Cet élément a une marque
de début et une de fin.</para>
<programlisting>
<![ CDATA [<p>C'est un paragraphe. Il commence avec la marque de début pour
l'élément 'p', et se terminera avec la marque de fin pour
l'élément 'p'</p>
<p>C'est un autre paragraphe. Mais il est beaucoup plus
court.</p>]]></programlisting>
</example>
<para>Tous les éléments n'ont pas besoin d'une marque de fin. Certains
n'ont pas de contenu. En HTML, par exemple, vous pouvez indiquer que
vous voulez avoir une ligne horizontal dans votre document. Cette ligne
n'a bien sûr aucun contenu, vous n'avez donc besoin que de la marque de
début pour cet élément.</para>
<example>
<title>Utiliser un élément (marque de début uniquement)</title>
<para>HTML dispose d'un élément pour inclure une ligne horizontale,
appelé <literal>hr</literal>. C'est un élément sans contenu, il n'a
donc qu'une marque de début.</para>
<programlisting>
<![ CDATA [<p>C'est un paragraphe.</p>
<hr>
<p>C'est un autre paragraphe. Une ligne horizontale le sépare
du précédent.</p>]]></programlisting>
</example>
<para>Si ce n'était pas encore clair, les éléments peuvent contenir
d'autres éléments. Dans l'exemple du livre plus haut, ce livre contenait
tous les chapitres, qui à leur tour contenaient tous les paragraphes, et
ainsi de suite.</para>
<example>
<title>Eléments dans des éléments ; <sgmltag>em</sgmltag></title>
<programlisting>
<![ CDATA [<p>C'est un <em>paragraphe</em> simple où certains
<em>mots</em> ont été <em>mis en valeur</em>.</p>]]></programlisting>
</example>
<para>La DTD définira les règles qui disent quels éléments peuvent être
inclus dans quels autres éléments, et ce qu'ils peuvent précisement
contenir.</para>
<important>
<para>Les gens confondent souvent marques et éléments comme si c'étaient
des termes interchangeables. Ce n'est pas le cas.</para>
<para>Un élément est une partie de la structure d'un document. Un
élément a un début et une fin. Les marques définissent où commence et
où finit le document.</para>
<para>Quand le présent document (ou quelqu'un d'autre qui connait le
SGML) parle de la marque “the <p> tag”, cela se
rapporte au texte composé des trois caractères
<literal><</literal>, <literal>p</literal>
et <literal>></literal>. Mais la phrase “l'élément
<p>” désigne tout l'élément.</para>
<para>Cette distinction <emphasis>est</emphasis> très subtile. Mais
gardez la à l'esprit.</para>
</important>
<para>Les éléments peuvent avoir des attributs. Un attribut a un nom et
une valeur, et sert à donner des informations supplémentaires
concernant l'élément. Ce peuvent être des informations qui précisent
comment l'élément doit être formaté, ou un identifiant unique pour cette
occurrence de l'élément, ou autre chose encore.</para>
<para>Les attributs d'un élément sont donnés <emphasis>dans</emphasis> la
marque de début de l'élément et ont la forme
<literal><replaceable>nom-de-l'attribut</replaceable>="<replaceable>valeur-de-l'attribut</replaceable>"</literal>.</para>
<para>Dans les versions récentes d'HTML, l'élément <sgmltag>p</sgmltag> a
un attribut appelé <literal>align</literal>, qui suggère un alignement
(justification) du paragraphe au programme affichant l'HTML.</para>
<para>L'attribut <literal>align</literal> peut prendre l'une des quatre
valeurs prédéfinies, <literal>left</literal>, <literal>center</literal>,
<literal>right</literal> et <literal>justify</literal>. Si l'attribut
n'est pas précise, la valeur par défaut est
<literal>left</literal>.</para>
<example>
<title>Utiliser un élément avec un attribut</title>
<programlisting>
<![ CDATA [<p align="left">L'attribut align est superflus pour ce paragraphe,
puisque 'left' est la valeur par défaut.</p>
<p align="center">Ce paragraphe sera peut-être centré.</p>]]></programlisting>
</example>
<para>Certains attributs ne prennent que des valeurs prédéfinies, comme
<literal>left</literal> ou <literal>justify</literal>. D'autres peuvent
prendre les valeurs que vous voulez. Si vous avez besoin de quotes
(<literal>"</literal>) dans un attribut, mettez la valeur de l'attribut
entre simples quotes.</para>
<example>
<title>Simples quotes dans un attribut</title>
<programlisting>
<![ CDATA [<p align='right'>Je suis à droite !</p>]]></programlisting>
</example>
<para>Vous n'avez pas toujours besoin de mettre la valeur de l'attribut
entre simples quotes. Les régles à ce sujet sont cependant subtiles, et
il est beaucoup plus simple de <emphasis>toujours</emphasis> mettre
entre simples quotes les valeurs des attributs.</para>
<sect2>
<title>A faire…</title>
<para>Pour tester les exemples donnés dans ce document, vous devrez
installer des logiciels sur votre système et vérifiez qu'une variable
d'environnement est correctement définie.</para>
<procedure>
<step>
<para>Téléchargez et installez <filename>textproc/docproj</filename>
du catalogue des logiciels portés de FreeBSD. C'est un
<emphasis>méta-port</emphasis> qui doit télécharger et installer
tous les programmes et fichiers utilisés par le Projet de
Documentation.</para>
</step>
<step>
<para>Ajoutez les lignes pour définir
<envar>SGML_CATALOG_FILES</envar> à vos procédures
d'initialisation de l'interpréteur de commandes.</para>
<example id="sgml-primer-envars">
<title><filename>.profile</filename>, pour les utilisateurs de
&man.sh.1; et &man.bash.1;</title>
<programlisting>
SGML_ROOT=/usr/local/share/sgml
SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
SGML_CATALOG_FILES=${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES
export SGML_CATALOG_FILES</programlisting>
</example>
<example>
<title><filename>.login</filename>, pour les utilisateurs de
&man.csh.1; et &man.tcsh.1;</title>
<programlisting>
setenv SGML_ROOT /usr/local/share/sgml
setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES</programlisting>
</example>
<para>Déconnectez-vous et reconnectez-vous ensuite, ou exécutez ces
commandes pour définir la variable d'environnement.</para>
</step>
<step>
<para>Créez un fichier <filename>exemple.sgml</filename>, où vous
mettrez :</para>
<programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0
Transitional//EN">
<html>
<head>
<title>Exemple de fichier HTML</title>
</head>
<body>
<p>C'est un paragraphe avec du texte.</p>
<p>C'est encore un paragraphe avec du texte.</p>
<p align="right">Ce paragraphe sera peut-être justifié à
droite.</p>
</body>
</html>]]></programlisting>
</step>
<step>
<para>Essayez de le valider avec un analyseur syntaxique
SGML.</para>
<para><link linkend="sgml-primer-validating">L'analyseur
syntaxique</link> &man.nsgmls.1; fait partie de
<filename>textproc/docproj</filename>. &man.nsgmls.1; lit
normalement un document marqué en utilisant une DTD SGML et génère
l'<foreignphrase>Element Structure Information Set
(ESIS)</foreignphrase> - Informations sur la
Structuration en Eléments - mais cela ne nous concerne
pas pour le moment.</para>
<para>Néanmoins, avec le paramètre <option>-s</option>,
&man.nsgmls.1; ne génère rien mais affiche simplement les messages
d'erreurs éventuels. C'est utile pour vérifier si votre document
est correct ou non.</para>
<para>Utilisez &man.nsgmls.1; pour vérifier si votre document est
valide :</para>
<screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput></screen>
<para>Vous constaterez que &man.nsgmls.1; n'affiche rien. Cela
signifie qu'il a validé votre document.</para>
</step>
<step>
<para>Voyez ce qui ce passe si vous oubliez un élément requis.
Supprimez les marques <sgmltag>title</sgmltag> et
<sgmltag>/title</sgmltag> et relancer la validation.</para>
<screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput>
nsgmls:example.sgml:5:4:E: character data is not allowed here
nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para>Les messages d'erreur de &man.nsgmls.1; sont structurés en
colonnes séparés par des deux-points ou des
points-virgules.</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Colonne</entry>
<entry>Signification</entry>
</row>
</thead>
<tbody>
<row>
<entry>1</entry>
<entry>Nom du programme qui a généré l'erreur. Ce sera
toujours <literal>nsgmls</literal>.</entry>
</row>
<row>
<entry>2</entry>
<entry>Nom du fichier où se trouve l'erreur.</entry>
</row>
<row>
<entry>3</entry>
<entry>Numéro de la ligne où se trouve l'erreur.</entry>
</row>
<row>
<entry>4</entry>
<entry>Numéro de la colonne où se trouve l'erreur.</entry>
</row>
<row>
<entry>5</entry>
<entry>Une lettre donnant le type de message d'erreur.
<literal>I</literal> pour un message d'information,
<literal>W</literal> pour un message d'avertissement,
<literal>E</literal> pour un message d'erreur et
<literal>X</literal> pour les références croisées. (Ce
n'est cependant pas toujours la cinquième colonne.
<command>nsgmls -sv</command> affiche
<literal>nsgmls:I: SP version
"1.3"</literal> - selon la version installée.
Comme vous pouvez le constater, c'est un message
d'information.) Vous voyez donc que nous avons dans notre
exemple des messages d'erreurs.</entry>
</row>
<row>
<entry>6</entry>
<entry>Le texte du message d'erreur.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para><ulink
url="http://www.cs.duke.edu/~dsb/kgv-faq/errors.html">Vous
aurez plus d'informations sur les erreurs de
&man.nsgmls.1;</ulink> dans la <ulink
url="http://www.cs.duke.edu/~dsb/kgv-faq/">Unofficial 'Kindler,
Gentler HTML Validator' FAQ</ulink>.</para>
<para>Ne pas mettre les marques <sgmltag>title</sgmltag> a généré
2 erreurs différentes.</para>
<para>La première erreur indique que l'analyseur SGML a rencontré un
contenu (ici, des caractères, au lieu d'une marque de début
d'élément) alors qu'il attendait autre chose. Dans le cas présent,
l'analyseur attendait une marque de début pour un élément valide
à l'intérieur de <sgmltag>head</sgmltag>
(<sgmltag>title</sgmltag> par exemple).</para>
<para>La deuxième erreur est due au fait que les éléments
<sgmltag>head</sgmltag> doivent contenir un élément
<sgmltag>title</sgmltag>. &man.nsgmls.1; considère alors que
l'élément n'est pas complet. La marque de fin indique donc que
l'élément se termine alors qu'il n'est pas correctement
renseigné.</para>
</step>
<step>
<para>Remettez l'élément <literal>title</literal> en place.</para>
</step>
</procedure>
</sect2>
</sect1>
<sect1 id="sgml-primer-doctype-declaration">
<title>La déclaration DOCTYPE</title>
<para>Au début de chaque document que vous rédigez, vous devez préciser le
nom de la DTD à laquelle le document se conforme. Cela pour que les
analyseurs syntaxiques SGML la connaissent et puissent valider le
document.</para>
<para>Cette information est habituellement donnée sur une seule ligne,
dans la déclaration DOCTYPE.</para>
<para>Voici une déclaration typique pour un document conforme à la version
4.0 de la DTD HTML :</para>
<programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting>
<para>Cette ligne a plusieurs composants distincts :</para>
<variablelist>
<varlistentry>
<term><literal><!</literal></term>
<listitem>
<para>C'est l'<emphasis>indicateur</emphasis> qui dit que c'est une
déclaration SGML. Cette ligne définit le type de document.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>DOCTYPE</literal></term>
<listitem>
<para>Précise que c'est la déclaration SGML du type de
document.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>html</literal></term>
<listitem>
<para>Définit le premier <link
linkend="sgml-primer-elements">élément</link> qui apparaîtra
dans le document.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term>
<listitem>
<para>Donne le <foreignphrase>Formal Public Identifier
(FPI)</foreignphrase> - Identifiant Public
Officiel - de la DTD à laquelle le document se
conforme.</para>
<para><literal>PUBLIC</literal> n'appartient pas au FPI, mais
indique au processeur SGML comment trouver la DTD référencée par
le FPI. Les autres façons de dire à l'analyseur SGML comment
trouver la DTD sont données <link
linkend="sgml-primer-fpi-alternatives">plus loin</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>></literal></term>
<listitem>
<para>Retour au document.</para>
</listitem>
</varlistentry>
</variablelist>
<sect2>
<title><foreignphrase>Formal Public Identifiers
(FPIs)</foreignphrase> - Identifiants Publics
Officiels</title>
<note>
<para>Vous n'avez pas besoin de connaître ce qui suit, mais ce n'est
n'est pas inutile, et cela peut vous aider à résoudre des problèmes,
si votre processeur SGML ne trouve pas la DTD que vous
utilisez.</para>
</note>
<para>Les FPIs doivent respecter une syntaxe précise. La
voici :</para>
<programlisting>
"<replaceable>Propriétaire</replaceable>//<replaceable>Mot-Clé</replaceable> <replaceable>Description</replaceable>//<replaceable>Langue</replaceable>"</programlisting>
<variablelist>
<varlistentry>
<term><replaceable>Propriétaire</replaceable></term>
<listitem>
<para>Indique qui détient le FPI.</para>
<para>Si la chaîne de caractères commence par “ISO”,
c'est un FPI ISO. Par exemple, le FPI <literal>"ISO
8879:1986//ENTITIES Greek Symbols//EN"</literal> donne
<literal>ISO 8879:1986</literal> comme propriétaire du jeu
d'entités pour les lettres grecques. ISO 8879:1986 est le
numéro ISO du standard SGML.</para>
<para>Sinon, cette chaîne sera de la forme
<literal>-//<replaceable>Propriétaire</replaceable></literal> ou
<literal>+//<replaceable>Propriétaire</replaceable></literal>
(remarquez que la seule différence est le <literal>+</literal>
ou <literal>-</literal> du début).</para>
<para>Si la chaîne commence par un <literal>-</literal>, c'est que
le propriétaire n'est pas enregistré, il l'est si elle commence
par un <literal>+</literal>.</para>
<para>L'ISO 9070:1991 définit comment sont générés les noms
enregistrés ; ils peuvent dériver du numéro d'une
publication ISO, d'un code ISBN ou d'un code d'organisation
affecté selon l'ISO 6523. De plus, il pourrait y avoir une
autorité d'enregistrement pour l'affectation de ces noms. Le
conseil ISO a délégué cela à l'<foreignphrase>American National
Standards Institute (ANSI)</foreignphrase> - Institut
National Américain des Standards.</para>
<para>Comme le Projet FreeBSD n'est pas enregistré, la chaîne
utilisée est <literal>-//FreeBSD</literal>. Comme vous pouvez
vous en rendre compte, le W3C n'est pas non plus un propriétaire
enregistré.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>Mot-Clé</replaceable></term>
<listitem>
<para>Il y a plusieurs mots-clés qui définissent le type
d'information dans le fichier. Les mots-clés les plus courants
sont : <literal>DTD</literal>, <literal>ELEMENT</literal>,
<literal>ENTITIES</literal> et <literal>TEXT</literal>.
<literal>DTD</literal> ne sert que pour les DTD,
<literal>ELEMENT</literal> sert habituellement pour les extraits
de DTD qui ne contiennent que des entités ou des déclarations
d'éléments. <literal>TEXT</literal> sert pour le contenu SGML
(texte et marques).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>Description</replaceable></term>
<listitem>
<para>La description que vous souhaitez donner du contenu du
fichier. Cela peut inclure des numéros de version et n'importe
quel texte court qui ait un sens et soit unique au système
SGML.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>Langue</replaceable></term>
<listitem>
<para>C'est une code ISO de deux caractères qui identifie la
langue utilisée dans le fichier. Pour l'anglais, c'est
<literal>EN</literal>.</para>
</listitem>
</varlistentry>
</variablelist>
<sect3>
<title>Fichiers <filename>catalog</filename></title>
<para>Si vous avez utilisé la syntaxe décrite plus haut et essayé
d'utiliser un processeur SGML pour traiter votre document, il aura
besoin de convertir le FPI en un nom de fichier sur votre ordinateur
qui décrive la DTD.</para>
<para>Vous pouvez pour cela vous servir d'un fichier catalogue
(habituellement appelé <filename>catalog</filename>). Il contient
des lignes qui donnent les correspondances entre FPIs et noms de
fichiers. Par exemple, s'il y a la ligne :</para>
<programlisting>
PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<para>le processeur SGML cherchera la DTD dans le fichier
<filename>strict.dtd</filename> du sous-répertoire
<filename>4.0</filename> où se trouve le fichier
<filename>catalog</filename> qui comporte cette ligne.</para>
<para>Jettez un oeil au fichier
<filename>/usr/local/share/sgml/html/catalog</filename>. C'est le
fichier catalogue pour les DTDs HTML qui ont été installées par le
logiciel porté <filename>textproc/docproj</filename>.</para>
</sect3>
<sect3>
<title><envar>SGML_CATALOG_FILES</envar></title>
<para>Pour trouver un fichier <filename>catalog</filename>, votre
processeur SGML doit savoir où chercher. La plupart d'entre eux ont
des paramètres de leur ligne de commande pour donner le chemin
d'accès à un ou plusieurs catalogues.</para>
<para>Vous pouvez par ailleurs définir
<envar>SGML_CATALOG_FILES</envar> pour désigner ces fichiers. Cette
variable d'environnement doit contenir une liste de fichiers
catalogues (donnés par leurs chemins d'accès complets) séparés par
des points-virgules.</para>
<para>Habituellement, vous incluerez les fichiers
suivants :</para>
<itemizedlist>
<listitem>
<para><filename>/usr/local/share/sgml/docbook/catalog</filename></para>
</listitem>
<listitem>
<para><filename>/usr/local/share/sgml/html/catalog</filename></para>
</listitem>
<listitem>
<para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para>
</listitem>
<listitem>
<para><filename>/usr/local/share/sgml/jade/catalog</filename></para>
</listitem>
</itemizedlist>
<!--
<para>Vous devriez <link linkend="sgml-primer-envars">déjà l'avoir
fait</link>.</para>
-->
</sect3>
</sect2>
<sect2 id="sgml-primer-fpi-alternatives">
<title>Alternatives aux FPIs</title>
<para>Au lieu d'utiliser un FPI pour préciser la DTD utilisée (et donc
le fichier qui contient la DTD), il est possible de donner
explicitement le nom du fichier.</para>
<para>La syntaxe pour le faire est légèrement différente :</para>
<programlisting>
<![ CDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting>
<para>Le mot-clé <literal>SYSTEM</literal> indique que le processeur
SGML doit localiser le fichier d'une façon qui dépend du système. Cela
signifie habituellement (mais pas toujours) que la DTD sera définie
par un nom de fichier.</para>
<para>Il est préférable d'utiliser des FPIs pour des raisons de
portabilité. Vous ne voulez pas livrer un exemplaire de la DTD avec
votre document, et si vous avez utilisé l'identifiant
<literal>SYSTEM</literal>, il faudra que chacun ait ses DTDs aux mêmes
endroits.</para>
</sect2>
</sect1>
<sect1 id="sgml-primer-sgml-escape">
<title>Revenir au SGML</title>
<para>On a dit plus haut dans cette introduction que le SGML n'était
utilisé que pour écrire les DTDs. Ce n'est pas tout à fait vrai. Il y a
des éléments de la syntaxe SGML que vous voudrez pouvoir utiliser dans
vos documents. Par exemple, vous pouvez y inclure des commentaires, qui
seront ignorés par les analyseurs. Les commentaires sont inclus en
utilisant une syntaxe SGML. D'autres utilisations du SGML dans les
documents seront mentionnées plus loin.</para>
<para>Il vous faut évidemment un moyen d'indiquer au processeur SGML que
ce qui va suivre n'est pas constitué d'éléments du document, mais est du
SGML que le processeur doit prendre en compte.</para>
<para>Ces sections sont marqués avec <literal><! ... ></literal>
dans votre document. Tout ce qui se trouve entre ces délimiteurs est du
code SGML comme on en trouve dans les DTDs.</para>
<para>Comme vous venez peut-être de vous en rendre compte, la <link
linkend="sgml-primer-doctype-declaration">déclaration DOCTYPE</link>
est un exemple de syntaxe SGML que vous devez inclure dans votre
document…</para>
</sect1>
<sect1>
<title>Commentaires</title>
&sgml.todo;
<para>Les commentaires suivent une syntaxe SGML et ne sont normalement
autorisés que dans une DTD. Cependant comme la
<xref linkend="sgml-primer-sgml-escape"> le montre, il est possible
d'inclure du SGML dans vos documents.</para>
<para>Les délimiteurs pour les commentaires SGML sont constitués de la
chaîne de caractères “<literal>--</literal>”. Une première
occurence ouvre le commentaire, et la seconde le ferme.</para>
<example>
<title>Commentaire SGML générique</title>
<programlisting>
<!-- commentaire de test --></programlisting>
<programlisting><![ CDATA [
<!-- C'est le texte du commentaire -->
<!-- C'est un autre commentaire -->
<!-- Voici une façon de mettre un commentaire
sur plusieurs lignes -->
<!-- Voici une autre façon --
-- de le faire -->]]></programlisting>
</example>
<![ %output.print; [
<important>
<title>Utilisez 2 tirets</title>
<para>Vous aurez un problème avec les versions PostScript et PDF de ce
document. Les exemples précédents n'auront probablement qu'un simple
tiret, <literal>-</literal> après <literal><!</literal> et avant
<literal>></literal>.</para>
<para>Il <emphasis>faut</emphasis> utiliser deux <literal>-</literal>,
et <emphasis>non</emphasis> un seul. Les versions PostScript et PDF
ont converti les deux <literal>-</literal> de l'original en un seul
<emphasis>double tiret</emphasis> plus professionnel, et déformé
l'exemple au passage.</para>
<para>Les versions HTML, texte et RTF de ce document ne sont pas
sujettes à ce problème.</para>
</important>
]]>
<para>Si vous avez déjà utilisé HTML auparavant, on vous a peut-être
donné des règles différentes pour les commentaires. En particulier, vous
pensez peut-être qu'ils commencent par <literal><!--</literal> et
ne se terminent qu'avec <literal>--></literal>.</para>
<para>Ce n'est <emphasis>pas</emphasis> le cas. Les analyseurs syntaxiques
de nombreux navigateurs sont défectueux et acceptent cette syntaxe. Ceux
qu'utilisent le Projet de Documentation sont plus rigoureux et
rejetteront les documents qui comportent cette erreur.</para>
<example>
<title>Commentaires SGML erronnés</title>
<programlisting><![ CDATA [
<!-- C'est en commentaire --
CE N'EST PAS EN COMMENTAIRE!
-- retour au commentaire -->]]></programlisting>
<para>L'analyseur SGML traitera cela comme s'il trouvait :</para>
<programlisting>
<!CE N'EST PAS EN COMMENTAIRE></programlisting>
<para>Ce qui n'est pas du SGML valide et donnera des messages d'erreur
source de confusion.</para>
<programlisting>
<![ CDATA [<!--------------- C'est un très mauvaise idée --------------->]]></programlisting>
<para>Comme l'exemple le suggère, ne mettez <emphasis>pas</emphasis> de
commentaires de ce type.</para>
<programlisting>
<![ CDATA [<!--===================================================-->]]></programlisting>
<para>C'est une (légèrement) meilleure idée, mais c'est toute de même
une source de confusion potentielle pour les débutants en SGML.</para>
</example>
<sect2>
<title>A faire…</title>
<procedure>
<step>
<para>Ajoutez des commentaires à <filename>exemple.sgml</filename>
et validez vos modifications avec &man.nsgmls.1;</para>
</step>
<step>
<para>Ajoutez des commentaires incorrects à
<filename>exemple.sgml</filename>, pour voir quels messages
d'erreur produit alors &man.nsgmls.1;.</para>
</step>
</procedure>
</sect2>
</sect1>
<sect1>
<title>Entités</title>
<para>Les entités fournissent un mécanisme pour désigner des parties d'un
contenu. Lorsque l'analyseur SGML traite votre document, il remplace les
entités qu'il rencontre par le contenu de ces entités.</para>
<para>C'est un bon moyen pour avoir du texte réutilisable et facile à
modifier. C'est aussi le seul moyen d'inclure, en utilisant SGML, un
fichier marqué dans un autre.</para>
<para>Il y a deux sortes d'entités SGML qui s'utilisent dans des
situations différentes : les <emphasis>entités générales</emphasis>
et les <emphasis>entités paramètres</emphasis>.</para>
<sect2 id="sgml-primer-general-entities">
<title>Entités Générales</title>
<para>Vous ne pouvez pas employer les entités générales dans un contexte
SGML (bien que ce soit là que vous les définissiez). Elles ne peuvent
être utilisées que dans votre document. Comparez cela au cas des
<link linkend="sgml-primer-parameter-entities">entités
paramètres</link>.</para>
<para>Chaque entité générale a un nom. Quand vous voulez y faire
référence (et donc inclure le texte qu'elle contient dans votre
document), vous mettez
<literal>&<replaceable>nom-de-l'entité</replaceable>;</literal>.
Supposons par exemple que vous ayez une entité appelée
<literal>version.courante</literal> qui contienne le numéro de version
courante de votre produit. Vous pourriez écrire :</para>
<programlisting>
<![ CDATA [<para>La version courante de notre produit est la
&version.courante;.</para>]]></programlisting>
<para>Quand le numéro de version change, il vous suffit de modifier la
définition de l'entité générale et de recompiler votre
document.</para>
<para>Vous pouvez aussi vous servir d'entités générales pour représenter
des caractères que vous ne pouvez pas inclure autrement dans un
document SGML. < et &, par exemple, ne doivent normalement pas
apparaître dans un document SGML. Quand l'analyseur SGML rencontre un
symbole <, il suppose qu'il précède une marque (de début ou de
fin), et quand il rencontre un symbole &, il suppose que le texte
qui le suit est le nom d'une entité.</para>
<para>Heureusement, il y a deux entités générales, &lt; et
&amp; pour le cas où vous auriez besoin d'inclure l'un ou l'autre
de ces symboles.</para>
<para>Une entité générale ne peut être définie que dans un contexte
SGML. On le fait habituellement immédiatement après la déclaration
DOCTYPE.</para>
<example>
<title>Définition d'entités générales</title>
<programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY version.courante "3.0-RELEASE">
<!ENTITY derniere.version "2.2.7-RELEASE">
]>]]></programlisting>
<para>Remarquez que la déclaration DOCTYPE est suivie d'un crochet
ouvrant à la fin de la première ligne. Les deux entités sont
définies aux deux lignes suivantes, avant le crochet fermant. La
déclaration DOCTYPE se termine ensuite.</para>
<para>Les crochets sont nécessaires pour dire que nous ajoutons un
complément à la DTD mentionnée par la déclaration DOCTYPE.</para>
</example>
</sect2>
<sect2 id="sgml-primer-parameter-entities">
<title>Entités paramètres</title>
<para>Comme les <link linkend="sgml-primer-general-entities">entités
générales</link>, les entités paramètres servent à nommer des
parties réutilisables du texte. Cependant, alors que les entités
générales peuvent être utilisées dans le corps du document, les
entités paramètres ne peuvent être employées que dans un
<link linkend="sgml-primer-sgml-escape">contexte SGML</link>.</para>
<para>Les entités paramètres sont définies de la même manière que les
entités générales. Sinon qu'au lieu de vous servir de
<literal>&<replaceable>inomd-de-l'entité</replaceable>;</literal>
pour y faire référence, vous utiliserez
<literal>%<replaceable>nom-de-l'entité</replaceable>;</literal><footnote>
<para>Les entités <emphasis>P</emphasis>aramètres employent le
symbole <emphasis>P</emphasis>ourcent.</para>
</footnote>. Leur définition comporte aussi un <literal>%</literal>
entre le mot-clé <literal>ENTITY</literal> et le nom de
l'entité.</para>
<example>
<title>Définition d'entités paramètres</title>
<programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % param.du "du">
<!ENTITY % param.texte "text">
<!ENTITY % param.encore "encore %param.du more %param.texte">
<!-- %param.encore contient maintenant "encore du texte" -->
]>]]></programlisting>
</example>
<para>Cela ne paraît peut être pas très utile. On verra pourtant que ça
l'est.</para>
</sect2>
<sect2>
<title>A faire…</title>
<procedure>
<step>
<para>Définissez un entité générale dans
<filename>exemple.sgml</filename>.</para>
<programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY version "1.1">
]>
<html>
<head>
<title>Exemple de fichier HTML</title>
</head>
<!-- Vous pourriez aussi mettre des commentaires ici -->
<body>
<p>C'est un paragraphe avec du texte.</p>
<p>C'est encore un paragraphe avec du texte.</p>
<p align="right">Ce paragraphe sera peut-être justifié à
droite</p>
<p>La version courante de ce document est : &version;</p>
</body>
</html>]]></programlisting>
</step>
<step>
<para>Validez le document avec &man.nsgmls.1;</para>
</step>
<step>
<para>Chargez <filename>exemple.sgml</filename> avec votre
navigateur (vous devrez peut-être le recopier dans
<filename>exemple.html</filename> pour que votre navigateur le
reconnaisse comme un document HTML).</para>
<para>A moins que votre navigateur ne soit très évolué, il ne
remplacera pas la référence <literal>&version;</literal>
à l'entité par le numéro de version. Les analyseurs de la plupart
des navigateurs sont élémentaires et ne gèrent pas correctement
le SGML<footnote><para>C'est tout à fait dommage. Imaginez les
problèmes et bricolages (comme les <foreignphrase>Server Side
Includes</foreignphrase>) que cela
éviterait.</para></footnote>.</para>
</step>
<step>
<para>La solution est de <emphasis>normaliser</emphasis> votre
document avec un outil de normalisation du SGML. Ce type d'outil
lit un document SGML valide et le transforme en un autre document
SGML tout aussi valide. En particulier, il y remplace les
références aux entités par leur contenu.</para>
<para>Vous pouvez le faire avec &man.sgmlnorm.1;.</para>
<screen>&prompt.user; <userinput>sgmlnorm exemple.sgml > exemple.html</userinput></screen>
<para><filename>exemple.html</filename> doit maintenant contenir une
version normalisée (i.e., où les références aux entités ont été
remplacées par leur contenu) de votre document, prête à être
affichée par votre navigateur.</para>
</step>
<step>
<para>Si vous jetez un oeil au résultat de &man.sgmlnorm.1;, vous
verrez qu'il ne comporte pas de déclaration DOCTYPE au début. Pour
qu'elle y soit, utilisez l'option
<option>-d</option> :</para>
<screen>&prompt.user; <userinput>sgmlnorm -d exemple.sgml > exemple.html</userinput></screen>
</step>
</procedure>
</sect2>
</sect1>
<sect1>
<title>Utiliser les entités pour inclure des fichiers</title>
<para>Les entités (<link
linkend="sgml-primer-general-entities">générales</link> et <link
linkend="sgml-primer-parameter-entities">paramètres</link>) sont
particulièrement utiles pour inclure un fichier dans un autre.</para>
<sect2 id="sgml-primer-include-using-gen-entities">
<title>Utiliser les entités générales pour inclure des fichiers</title>
<para>Supposons que le contenu d'un livre SGML soit découpé en fichiers,
à raison d'un fichier par chapitre, appelés
<filename>chaptitre1.sgml</filename>,
<filename>chapitre2.sgml</filename>, et ainsi de suite, et que le
fichier <filename>livre.sgml</filename> inclue ces chapitres.</para>
<para>Pour que vos entités aient pour valeur le contenu de ces fichiers,
vous les déclarerez avec le mot-clé <literal>SYSTEM</literal>. Cela
indique à l'analyseur SGML qu'il doit utiliser le contenu du fichier
mentionné comme valeur de l'entité.</para>
<example>
<title>Utiliser les entités générales pour inclure des
fichiers</title>
<programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY chapitre.1 SYSTEM "chapitre1.sgml">
<!ENTITY chapitre.2 SYSTEM "chapitre2.sgml">
<!ENTITY chapitre.3 SYSTEM "chapitre3.sgml">
<!-- Et ainsi de suite -->
]>
<html>
<!-- Utilisation des entités pour inclure les chapitres -->
&chapitre.1;
&chapitre.2;
&chapitre.3;
</html>]]></programlisting>
</example>
<warning>
<para>Quand vous vous servez d'entités générales pour inclure d'autres
fichiers dans un document, les fichiers inclus
(<filename>chapitre1.sgml</filename>,
<filename>chapitre2.sgml</filename>, et ainsi de suite) ne doivent
<emphasis>pas</emphasis> commencer par une déclaration DOCTYPE. Ce
serait une erreur de syntaxe.</para>
</warning>
</sect2>
<sect2>
<title>Utiliser les entités paramètres pour inclure des fichiers</title>
<para>Rappelez-vous que les entités paramètres ne peuvent être utilisées
que dans un contexte SGML. Quand aurez-vous besoin d'inclure un
fichier dans un contexte SGML ?</para>
<para>Vous pouvez vous en servir pour être sûr de pouvoir réutiliser vos
entités générales.</para>
<para>Supposons que votre document comporte de nombreux chapitres, et
que vous réutilisiez ces chapitres dans deux livres différents, chacun
organisant ces chapitres de façon différente.</para>
<para>Vous pourriez donner la liste des entités en tête de chaque livre,
mais cela pourrait rapidement devenit fastidieux à gérer.</para>
<para>Mettez, au lieu de cela, les définitions des entités générales
dans un fichier, et utilisez une entité paramètre pour inclure ce
fichier dans votre document.</para>
<example>
<title>Utiliser les entités paramètres pour inclure des
fichiers</title>
<para>Mettez d'abord les définitions de vos entités dans un fichier
séparé, appelé <filename>chapitres.ent</filename>. Voici ce qu'il
contiendra :</para>
<programlisting>
<![ CDATA [<!ENTITY chapitre.1 SYSTEM "chapitre1.sgml">
<!ENTITY chapitre.2 SYSTEM "chapitre2.sgml">
<!ENTITY chapitre.3 SYSTEM "chapitre3.sgml">]]></programlisting>
<para>Créez maintenant une entité paramètre qui fasse référence au
contenu de ce fichier. Utilisez ensuite cette entité pour inclure
le fichier dans votre document, vous pourrez alors y utiliser les
entités générales. Ce que vous faites de la même façon que
précédemment :</para>
<programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!--
Définissez une entité paramètre pour inclure le fichier
des entités générales pour les chapitres
-->
<!ENTITY % chapitres SYSTEM "chapitres.ent">
<!-- Utilisez maintenant l'entité générale pour inclure ce fichier -->
%chapitres;
]>
<html>
&chapitre.1;
&chapitre.2;
&chapitre.3;
</html>]]></programlisting>
</example>
</sect2>
<sect2>
<title>A faire…</title>
<sect3>
<title>Utiliser les entités générales pour inclure des fichiers</title>
<procedure>
<step>
<para>Créez trois fichiers, <filename>para1.sgml</filename>,
<filename>para2.sgml</filename> et
<filename>para3.sgml</filename>.</para>
<para>Mettez-y quelque chose qui ressemble à ceci :</para>
<programlisting>
<![ CDATA [<p>C'est le premier paragraphe.</p>]]></programlisting>
</step>
<step>
<para>Modifiez <filename>exemple.sgml</filename> de la façon
suivante :</para>
<programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.sgml">
<!ENTITY para2 SYSTEM "para2.sgml">
<!ENTITY para3 SYSTEM "para3.sgml">
]>
<html>
<head>
<title>Exemple de fichier HTML</title>
</head>
<body>
<p>La version courante de ce document est : &version;</p>
¶1;
¶2;
¶3;
</body>
</html>]]></programlisting>
</step>
<step>
<para>Générez <filename>exemple.html</filename> en normalisant
<filename>exemple.sgml</filename>.</para>
<screen>&prompt.user; <userinput>sgmlnorm -d exemple.sgml > exemple.html</userinput></screen>
</step>
<step>
<para>Affichez <filename>exemple.html</filename> avec votre
navigateur Web et vérifiez que les fichiers
<filename>para<replaceable>n</replaceable>.sgml</filename> ont
bien été inclus dans <filename>exemple.html</filename>.</para>
</step>
</procedure>
</sect3>
<sect3>
<title>Utiliser les entités paramètres pour inclure des
fichiers</title>
<note>
<para>Vous devez d'abord avoir mis en pratique l'exemple
précédent.</para>
</note>
<procedure>
<step>
<para>Modifiez comme ceci
<filename>exemple.sgml</filename> :</para>
<programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % entites SYSTEM "entites.sgml"> %entites;
]>
<html>
<head>
<title>Exemple de fichier HTML</title>
</head>
<body>
<p>La version courant de ce document est : &version;</p>
¶1;
¶2;
¶3;
</body>
</html>]]></programlisting>
</step>
<step>
<para>Créez un nouveau fichier, <filename>entites.sgml</filename>,
qui contienne :</para>
<programlisting>
<![ CDATA [<!ENTITY version "1.1">
<!ENTITY para1 SYSTEM "para1.sgml">
<!ENTITY para2 SYSTEM "para2.sgml">
<!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting>
</step>
<step>
<para>Générez <filename>exemple.html</filename> en normalisant
<filename>exemple.sgml</filename>.</para>
<screen>&prompt.user; <userinput>sgmlnorm -d exemple.sgml > exemple.html</userinput></screen>
</step>
<step>
<para>Affichez <filename>exemple.html</filename> avec votre
navigateur Web et vérifiez que les fichiers
<filename>para<replaceable>n</replaceable>.sgml</filename> ont
bien été inclus dans <filename>example.html</filename>.</para>
</step>
</procedure>
</sect3>
</sect2>
</sect1>
<sect1 id="sgml-primer-marked-sections">
<title>Sections marquées</title>
<para>SGML fournit un mécanisme pour définir quelles parties d'un document
doivent être traitées de façon particulière. On appelle cela des
“sections marquées”.</para>
<example>
<title>Structure d'une section marquée</title>
<programlisting>
<![ <replaceable>MOT-CLE</replaceable> [
Contenu de la section marquée
]]></programlisting>
</example>
<para>Comme vous pouviez vous y attendre, une section marquée est une
fonctionnalité SGML et commence donc par <literal><!</literal>.</para>
<para>Le premier crochet ouvrant délimite la section marquée.</para>
<para>Le <replaceable>MOT-CLE</replaceable> définit comment cette section
marquée doit être traitée par l'analyseur.</para>
<para>Le second crochet ouvrant indique que le contenu de la section
marquée commence là.</para>
<para>La section marquée se termine par deux crochets fermants, puis un
<literal>></literal> pour indiquer que l'on quitte le contexte SGML
et que l'on revient au document.</para>
<sect2>
<title>Mots-clés pour les sections marquées</title>
<sect3>
<title><literal>CDATA</literal>, <literal>RCDATA</literal></title>
<para>Ces deux mots-clés définissent des sections marquées comme
<emphasis>modèle de contenu</emphasis> et vous permettent de
modifier sa valeur par défaut.</para>
<para>Quand un analyseur SGML traite un docuemnt, il mémorise ce que
l'on appelle le “modèle de contenu”.</para>
<para>En bref, le modèle de contenu décrit ce que l'analyseur doit
s'attendre à trouver comme contenu, et ce qu'il doit en faire quand
il le rencontre.</para>
<para>Les deux modèles de contenu que vous trouverez certainement les
plus utiles sont <literal>CDATA</literal> et
<literal>RCDATA</literal>.</para>
<para><literal>CDATA</literal> signifie
“<foreignphrase>Character
Data</foreignphrase>” - données caractères. Si
l'analyseur est à l'intérieur de ce modèle de contenu, il s'attend
à trouver des caractères, et uniquement des caractères. Les
symboles < et & perdent alors leur signification particulière
et sont traités comme de simples caractères.</para>
<para><literal>RCDATA</literal> signifie “Références à des
entités et données caractères”. Si l'analyseur est à
l'intérieur de ce modèle de contenu, il s'attend à trouver des
caractères <emphasis>et</emphasis> des entités. < perd sa
signification particulière, mais & est toujours compris comme le
début d'une entité générale.</para>
<para>C'est particulièrement utile si vous incluez du texte qui
contient de nombreux caractères < et &. Vous pourriez bien
sûr contrôler que dans votre texte tous les < sont écrits
&lt; et tous les & &amp;, il peut être plus facile
de marquer la section comme ne contenant que des
“CDATA”. Quand SGML rencontre l'instruction
correspondante, il ignorera les symboles < et & qui
apparaîtront dans le contenu.</para>
<!-- The nesting of CDATA within the next example is disgusting -->
<example>
<title>Utiliser une section marquée CDATA</title>
<programlisting>
<para>Voici un exemple de la façon dont vous pourriez inclure
un texte comportant de nombreux &lt; et &amp;. L'exemple
lui-même est en HTML. Le texte qui l'encadre (<para> et
<programlisting>) est du DocBook.</para>
<programlisting>
<![ CDATA [ <![ CDATA [
<p>Cet exemple vous montre quelques éléments de HTML. Comme les
caractères < et > y sont si fréquemment utilisés, il est plus
facile de marquer tout l'exemple comme CDATA plutôt que de se
servir des entités à la place de ces caractères dans tout le
texte.</p>
<ul>
<li>C'est un élément de liste</li>
<li>C'est un second élément de liste</li>
<li>C'est un troisième élément de liste</li>
</ul>
<p>C'est la fin de l'exemple.</p>]]>
]]>
</programlisting></programlisting>
<para>Si vous consultez le source de ce document, vous verrez qu'il
utilise constamment cette technique.</para>
</example>
</sect3>
<sect3>
<title><literal>INCLUDE</literal> et <literal>IGNORE</literal></title>
<para>Si le mot-clé est <literal>INCLUDE</literal>, alors le contenu
de la section marquée sera pris en compte. Si le mot-clé est
<literal>IGNORE</literal>, alors la section marquée sera ignorée. Il
n'apparaîtra pas dans les sorties.</para>
<example>
<title>Utiliser <literal>INCLUDE</literal> et
<literal>IGNORE</literal> dans les sections marquées</title>
<programlisting>
<![ INCLUDE [
Ce texte sera traité et inclus.
]]>
<![ IGNORE [
Ce texte ne sera pas traité ou inclus.
]]></programlisting>
</example>
<para>En soi, cela ne sert pas à grand-chose. Si vous vouliez
supprimer du texte de votre document, vous auriez pu l'enlever ou le
mettre en commentaires.</para>
<para>Cela devient plus utile quand vous comprenez que vous pouvez
vous servir des <link
linkend="sgml-primer-parameter-entities">entités paramètres</link>
pour contrôler ces sections. Rappelez-vous que les entités
paramètres ne peuvent être utilisées que dans un contexte SGML, et
une section marquée <emphasis>est</emphasis> un contexte SGML.</para>
<para>Si par exemple, vous générez une version imprimée et une version
électronique de votre document, vous pourriez vouloir inclure dans
la version électronique un contenu supplémentaire qui ne devra pas
apparaître dans la version imprimée.</para>
<para>Créez une entité paramètre et donnez lui comme contenu
<literal>INCLUDE</literal>. Rédigez votre document en utilisant des
sections marquées pour délimiter le contenu qui ne doit apparaître
que dans la version électronique. Dans ces sections marquées,
servez-vous de l'entité paramètre au lieu du mot-clé.</para>
<para>Lorsque vous voulez générer la version électronique, changez la
valeur de l'entité paramètre en <literal>IGNORE</literal> et
retraitez le document.</para>
<example>
<title>Utiliser une entité paramètre pour contrôler une section
marquée</title>
<programlisting>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % version.electronique "INCLUDE">
]]>
...
<![ %version.electronique [
Ce texte ne doit apparaître que dans
la version électronique du document.
]]></programlisting>
<para>Pour générer la version imprimée, changez la définition de
l'entité en :</para>
<programlisting>
<!ENTiTY % version.electronique "IGNORE"></programlisting>
<para>A la seconde passe sur le document, les sections marquées qui
utilisent <literal>%version.electronique</literal> comme mot-clé
seront ignorées.</para>
</example>
</sect3>
</sect2>
<sect2>
<title>A faire…</title>
<procedure>
<step>
<para>Créez un nouveau fichier, <filename>section.sgml</filename>,
qui contienne :</para>
<programlisting>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % text.output "INCLUDE">
]>
<html>
<head>
<title>Exemple d'utilisation des sections marquées</title>
</head>
<body>
<p>Ce paragraphe <![ CDATA [contient de nombreux
caractères < (< < < < <) il est donc
plus facile de l'inclure dans une section marquée
CDATA ]]></p>
<![ IGNORE [
<p>Ce paragraphe n'apparaîtra jamais dans les
sorties.</p>
]]>
<![ <![ CDATA [%sortie.texte]]> [
<p>Ce paragraphe apparaîtra peut-être dans les
sorties.</p>
<p>Cela dépend de l'entité paramètre
<![CDATA[%sortie.texte]]>.</p>
]]>
</body>
</html></programlisting>
</step>
<step>
<para>Normalisez le fichier avec &man.sgmlnorm.1; et examinez le
résultat. Notez quels paragraphes ont été conservés et quels
paragraphes ont été supprimés, et ce qu'est devenu le contenu des
sections marquées CDATA.</para>
</step>
<step>
<para>Modifiez la définition de l'entité
<literal>sortie.texte</literal> de <literal>INCLUDE</literal> en
<literal>IGNORE</literal>. Normalisez de nouveau le fichier et
regardez ce qui a changé dans le résultat.</para>
</step>
</procedure>
</sect2>
</sect1>
<sect1>
<title>Conclusion</title>
<para>Ici se termine cette introduction à SGML. Pour des raisons de place
et de complexité, de nombreux points ont été survolés (voire omis).
Les sections qui précédent décrivent néanmoins suffisamment d'éléments
du SGML pour vous permettre de comprendre comment est organisée la
documentation du FDP.</para>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->
|