-
Notifications
You must be signed in to change notification settings - Fork 7
/
PressGang CCMS Handbook.html
3281 lines (3143 loc) · 420 KB
/
PressGang CCMS Handbook.html
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
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>PressGang CCMS Handbook</title><link rel="stylesheet" type="text/css" href="Common_Content/css/default.css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 3.1.5" /><meta name="package" content="PressGang_CCMS-PressGang_CCMS_Handbook-2.0-en-US-1.0.0-1" /><meta name="description" content="This guide represents the workflows and methods which generate the best results for CCMS-generated documentation, and should be used as the first point of guidance for using PressGang CCMS" /></head><body><p id="title"><a class="left" href="http://www.redhat.com"><img alt="Product Site" src="Common_Content/images//image_left.png" /></a><a class="right" href="https://access.redhat.com/site/documentation/"><img alt="Documentation Site" src="Common_Content/images//image_right.png" /></a></p><div class="book"><div class="titlepage"><div><div class="producttitle"><span class="productname">PressGang CCMS</span> <span class="productnumber">2.0</span></div><div><h1 class="title"><a id="idm1039680"></a>PressGang CCMS Handbook</h1></div><div><h2 class="subtitle">Guidelines for Writers, Information Architects, Translators, and other Users</h2></div><p class="edition">Edition 1</p><div><h3 class="corpauthor">
<span class="inlinemediaobject"><object data="Common_Content/images/title_logo.svg" type="image/svg+xml"> </object></span>
</h3></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Misha</span> <span class="surname">Husnain Ali</span></h3><div class="affiliation"><span class="orgname"> Red Hat </span> <span class="orgdiv"> Engineering Content Services </span></div><code class="email"><a class="email" href="mailto:mhusnain@redhat.com">mhusnain@redhat.com</a></code></div><div class="author"><h3 class="author"><span class="firstname">Misty</span> <span class="surname">Stanley-Jones</span></h3><code class="email"><a class="email" href="mailto:misty@redhat.com">misty@redhat.com</a></code></div></div></div><div><div class="legalnotice"><a id="idp20631856"></a><h1 class="legalnotice">Legal Notice</h1><div class="para">
Copyright <span class="trademark"></span>© 2013 Red Hat, Inc..
</div><div class="para">
This document is licensed by Red Hat under the <a href="http://creativecommons.org/licenses/by-sa/3.0/" target="_top">Creative Commons Attribution-ShareAlike 3.0 Unported License</a>. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
</div><div class="para">
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
</div><div class="para">
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
</div><div class="para">
<span class="trademark">Linux</span>® is the registered trademark of Linus Torvalds in the United States and other countries.
</div><div class="para">
<span class="trademark">Java</span>® is a registered trademark of Oracle and/or its affiliates.
</div><div class="para">
<span class="trademark">XFS</span>® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
</div><div class="para">
<span class="trademark">MySQL</span>® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
</div><div class="para">
<span class="trademark">Node.js</span>® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
</div><div class="para">
All other trademarks are the property of their respective owners.
</div><div class="para">
<div class="address"><p><br />
<span class="street">1801 Varsity Drive</span><br />
<span class="city">Raleigh</span>, <span class="state">NC</span> <span class="postcode">27606-2072</span> <span class="country">USA</span><br />
<span class="phone">Phone: +1 919 754 3700</span><br />
<span class="phone">Phone: 888 733 4281</span><br />
<span class="fax">Fax: +1 919 754 3701</span></p></div>
</div></div></div><div><div class="abstract"><p class="title"><strong>Abstract</strong></p><div class="para">
This guide represents the workflows and methods which generate the best results for CCMS-generated documentation, and should be used as the first point of guidance for using PressGang CCMS
</div></div></div></div></div><div class="toc"><dl><dt><span class="preface"><a href="#pref-PressGang_CCMS_Handbook-Preface">Preface</a></span></dt><dd><dl><dt><span class="section"><a href="#idp18735264">1. Document Conventions</a></span></dt><dd><dl><dt><span class="section"><a href="#idp18738144">1.1. Typographic Conventions</a></span></dt><dt><span class="section"><a href="#idp17449520">1.2. Pull-quote Conventions</a></span></dt><dt><span class="section"><a href="#idp20265904">1.3. Notes and Warnings</a></span></dt></dl></dd><dt><span class="section"><a href="#sect_RedHat-Getting_Help_and_Giving_Feedback">2. Getting Help and Giving Feedback</a></span></dt><dd><dl><dt><span class="section"><a href="#sect_RedHat-Do_You_Need_Help">2.1. Do You Need Help?</a></span></dt><dt><span class="section"><a href="#sect-RedHat-We_Need_Feedback">2.2. We Need Feedback</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chap-Introduction">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#About_This_Guide">1.1. About This Guide</a></span></dt><dt><span class="section"><a href="#About_PressGang_CCMS">1.2. About PressGang CCMS</a></span></dt><dt><span class="section"><a href="#Known_Issues_and_Limitations">1.3. Known Issues and Limitations</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Topic-Based_Authoring_in_the_CCMS">2. Topic-Based Authoring in the CCMS</a></span></dt><dd><dl><dt><span class="section"><a href="#About_Topic-Based_Authoring1">2.1. About Topic-Based Authoring</a></span></dt><dt><span class="section"><a href="#sect-Topic_Types">2.2. Topic Types</a></span></dt><dd><dl><dt><span class="section"><a href="#Content">2.2.1. Concept</a></span></dt><dt><span class="section"><a href="#Task3">2.2.2. Task</a></span></dt><dt><span class="section"><a href="#Reference4">2.2.3. Reference</a></span></dt><dt><span class="section"><a href="#CSProcessor_Map">2.2.4. CSProcessor Map</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Metadata">2.3. Metadata</a></span></dt><dd><dl><dt><span class="section"><a href="#Per-Topic_Metadata">2.3.1. Per-Topic Metadata</a></span></dt><dt><span class="section"><a href="#Per-Map_Metadata">2.3.2. Per-Map Metadata</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chap-Planning_and_Designing_Documents">3. Planning and Designing Documents</a></span></dt><dd><dl><dt><span class="section"><a href="#About_Topic-Based_Authoring1-1">3.1. About Topic-Based Authoring</a></span></dt><dt><span class="section"><a href="#About_Content_Specifications">3.2. About Content Specifications</a></span></dt><dt><span class="section"><a href="#About_CSProcessor">3.3. About CSProcessor</a></span></dt><dt><span class="section"><a href="#sect-Using_the_CSProcessor">3.4. Using the CSProcessor</a></span></dt><dd><dl><dt><span class="section"><a href="#Install_CSProcessor">3.4.1. Install CSProcessor</a></span></dt><dt><span class="section"><a href="#Use_the_csprocessor_Command">3.4.2. Use the <code class="code">csprocessor</code> Command</a></span></dt><dt><span class="section"><a href="#sect-CSProcessor_Map_Syntax">3.4.3. CSProcessor Map Syntax</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Designing_Documents">3.5. Designing Documents</a></span></dt><dd><dl><dt><span class="section"><a href="#Create_a_Map">3.5.1. Create a Map</a></span></dt><dt><span class="section"><a href="#Modify_a_Map">3.5.2. Modify a Map</a></span></dt><dt><span class="section"><a href="#Freeze_a_Map">3.5.3. Freeze a Map</a></span></dt><dt><span class="section"><a href="#Clone_a_Map">3.5.4. Clone a Map</a></span></dt><dt><span class="section"><a href="#Build_a_Book_from_a_Map">3.5.5. Build a Book from a Map</a></span></dt><dt><span class="section"><a href="#Request_a_Continuous_Integration_Book">3.5.6. Request a Continuous Integration Book</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-CSProcessor_Map_Workflow">3.6. CSProcessor Map Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#About_the_Workflow_Phases">3.6.1. About the Workflow Phases</a></span></dt><dt><span class="section"><a href="#Move_the_Map_to_the_Next_Phase">3.6.2. Move the Map to the Next Phase</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Version_Control_in_the_CCMS">3.7. Version Control in the CCMS</a></span></dt><dd><dl><dt><span class="section"><a href="#Topic_Revisions">3.7.1. Topic Revisions</a></span></dt><dt><span class="section"><a href="#Revision-less_Trunk_CSProcessor_Maps">3.7.2. Revision-less (Trunk) and Frozen CSProcessor Maps</a></span></dt><dt><span class="section"><a href="#Modify_a_Topics_Revision_in_a_Frozen_Map">3.7.3. Modify a Topic's Revision in a Frozen Map</a></span></dt><dt><span class="section"><a href="#Compare_Revisions_of_a_Topic">3.7.4. Compare Revisions of a Topic</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chap-Writing_in_the_CCMS">4. Writing in the CCMS</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-About_the_UI">4.1. About the UI</a></span></dt><dd><dl><dt><span class="section"><a href="#User_Interface_Conventions">4.1.1. User Interface Conventions</a></span></dt><dt><span class="section"><a href="#sect-Navigation_Elements">4.1.2. Navigation Elements</a></span></dt><dt><span class="section"><a href="#The_Editor">4.1.3. The Editor</a></span></dt></dl></dd><dt><span class="section"><a href="#Considerations_for_Topic_Reuse">4.2. Considerations for Topic Reuse</a></span></dt><dt><span class="section"><a href="#Typical_Writing_Workflow">4.3. Typical Writing Workflow</a></span></dt><dt><span class="section"><a href="#sect-Writing_Topics">4.4. Writing Topics</a></span></dt><dd><dl><dt><span class="section"><a href="#Search_for_Work">4.4.1. Search for Work</a></span></dt><dt><span class="section"><a href="#Claim_a_Topic">4.4.2. Claim a Topic</a></span></dt><dt><span class="section"><a href="#Write_or_Modify_the_Topic">4.4.3. Write or Modify the Topic</a></span></dt><dt><span class="section"><a href="#Use_the_Web-Based_Editor">4.4.4. Use the Web-Based Editor</a></span></dt><dt><span class="section"><a href="#Debug_a_Build_Error_in_DocBuilder">4.4.5. Debug a Build Error in DocBuilder</a></span></dt><dt><span class="section"><a href="#Edit_Metadata">4.4.6. Edit Metadata</a></span></dt><dt><span class="section"><a href="#Log_Revision_Messages">4.4.7. Log Revision Messages</a></span></dt><dt><span class="section"><a href="#Request_Topic_Map_Updates">4.4.8. Request Topic Map Updates</a></span></dt><dt><span class="section"><a href="#Request_Peer_Review">4.4.9. Request Peer Review</a></span></dt><dt><span class="section"><a href="#Request_SME_QE_Review">4.4.10. Request SME / QE Review</a></span></dt><dt><span class="section"><a href="#Move_a_Topic_to_the_Next_Phase">4.4.11. Move a Topic to the Next Phase</a></span></dt><dt><span class="section"><a href="#Move_a_Topic_to_the_Previous_Phase">4.4.12. Move a Topic to the Previous Phase</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Creating_and_Using_Tags">4.5. Creating and Using Tags</a></span></dt><dd><dl><dt><span class="section"><a href="#About_CCMS_UI_Tags">4.5.1. About CCMS UI Tags</a></span></dt><dt><span class="section"><a href="#Add_a_New_Tag">4.5.2. Add a New Tag</a></span></dt><dt><span class="section"><a href="#About_Editing_Tags">4.5.3. About Editing Tags</a></span></dt><dt><span class="section"><a href="#Modify_Tag_Properties">4.5.4. Modify Tag Properties</a></span></dt><dt><span class="section"><a href="#Add_a_Tag_to_Additional_Projects">4.5.5. Add a Tag to Additional Projects</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-CCMS-Specific_Syntax_and_Tooling">4.6. CCMS-Specific Syntax and Tooling</a></span></dt><dd><dl><dt><span class="section"><a href="#sect-Referring_to_Other_Content">4.6.1. Referring to Other Content</a></span></dt><dt><span class="section"><a href="#sect-Conditional_Build_Statements">4.6.2. Conditional Build Statements</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Searching">4.7. Searching</a></span></dt><dd><dl><dt><span class="section"><a href="#About_Search_Options_in_the_CCMS">4.7.1. About Search Options in the CCMS</a></span></dt><dt><span class="section"><a href="#Perform_a_Search">4.7.2. Perform a Search</a></span></dt><dt><span class="section"><a href="#Save_a_Search">4.7.3. Save a Search</a></span></dt><dt><span class="section"><a href="#Example_Useful_Searches">4.7.4. Example Useful Searches</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Interact_with_External_Systems">4.8. Interact with External Systems</a></span></dt><dd><dl><dt><span class="section"><a href="#Work_with_Bugzilla">4.8.1. Work with Bugzilla</a></span></dt><dt><span class="section"><a href="#View_Reports">4.8.2. View Reports</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Graphics_in_the_CCMS">4.9. Graphics in the CCMS</a></span></dt><dd><dl><dt><span class="section"><a href="#About_Graphics_in_the_CCMS">4.9.1. About Graphics in the CCMS</a></span></dt><dt><span class="section"><a href="#Upload_an_Image1">4.9.2. Upload an Image</a></span></dt><dt><span class="section"><a href="#Use_the_Bulk_Image_Uploader">4.9.3. Use the Bulk Image Uploader</a></span></dt><dt><span class="section"><a href="#Update_an_Image">4.9.4. Update an Image</a></span></dt><dt><span class="section"><a href="#Upload_Localized_Screenshots">4.9.5. Upload Localized Images</a></span></dt><dt><span class="section"><a href="#Use_an_Image_in_a_Topic">4.9.6. Use an Image in a Topic</a></span></dt><dt><span class="section"><a href="#Use_a_Specific_Version_of_an_Image_In_a_Topic">4.9.7. Use a Specific Version of an Image In a Topic</a></span></dt><dt><span class="section"><a href="#View_all_Topics_that_Use_a_Particular_Image">4.9.8. View all Topics that Use a Particular Image</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#chap-Translation_in_the_CCMS">5. Translation in the CCMS</a></span></dt><dd><dl><dt><span class="section"><a href="#Translation_Workflow_in_the_CCMS">5.1. Translation Workflow in the CCMS</a></span></dt><dt><span class="section"><a href="#Freeze_a_Map-1">5.2. Freeze a Map</a></span></dt><dt><span class="section"><a href="#Push_English_Strings_to_Zanata">5.3. Push English Strings to Zanata</a></span></dt><dt><span class="section"><a href="#Initiate_Translation_Memory_on_Freshly_Pushed_Content">5.4. Initiate Translation Memory on Freshly Pushed Content</a></span></dt><dt><span class="section"><a href="#Pull_Translated_Strings_from_Zanata">5.5. Pull Translated Strings from Zanata</a></span></dt><dt><span class="section"><a href="#View_a_Continuous_Integration_Build_of_In-Progress_Translations">5.6. View a Continuous Integration Build of In-Progress Translations</a></span></dt><dt><span class="section"><a href="#Publish_a_Translated_Book_from_a_Map">5.7. Publish a Translated Book from a Map</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Migrating_Content_to_the_CCMS">6. Migrating Content to the CCMS</a></span></dt><dd><dl><dt><span class="section"><a href="#Suggested_Migration_Workflow">6.1. Suggested Migration Workflow</a></span></dt><dt><span class="section"><a href="#Get_Content_Ready_to_Move">6.2. Get Content Ready to Move</a></span></dt><dt><span class="section"><a href="#Create_Maps_to_Mirror_Existing_Structure">6.3. Create Maps to Mirror Existing Structure</a></span></dt><dt><span class="section"><a href="#Import_Content_to_Topics">6.4. Import Content to Topics</a></span></dt><dt><span class="section"><a href="#Import_Images">6.5. Import Images</a></span></dt><dt><span class="section"><a href="#Import_Translation_Strings_to_Zanata">6.6. Import Translation Strings to Zanata</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Working_with_Upstreams">7. Working with Upstreams</a></span></dt><dd><dl><dt><span class="section"><a href="#Add_Maven_and_jDocBook_Support">7.1. Add Maven and jDocBook Support</a></span></dt><dt><span class="section"><a href="#Suggested_Workflow_for_Upstream_SVN">7.2. Suggested Workflow for Upstream SVN</a></span></dt><dt><span class="section"><a href="#Suggested_Workflow_for_Upstream_GIT">7.3. Suggested Workflow for Upstream GIT</a></span></dt><dt><span class="section"><a href="#Suggested_Workflow_for_Upstream_Confluence">7.4. Suggested Workflow for Upstream Confluence</a></span></dt><dt><span class="section"><a href="#Suggested_Workflow_for_Upstream_AsciiDoc">7.5. Suggested Workflow for Upstream AsciiDoc</a></span></dt><dt><span class="section"><a href="#Suggested_Workflow_for_Upstream_MarkDown">7.6. Suggested Workflow for Upstream MarkDown</a></span></dt></dl></dd><dt><span class="chapter"><a href="#chap-Appendix">8. Appendix</a></span></dt><dd><dl><dt><span class="section"><a href="#Resources2">8.1. Resources</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp4248880">9. Compiler Output</a></span></dt><dd><dl><dt><span class="glossary"><a href="#idp8022672">Compiler Glossary</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idp6054544">10. Status Report</a></span></dt><dt><span class="appendix"><a href="#appe-PressGang_CCMS_Handbook-Revision_History">A. Revision History</a></span></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a id="pref-PressGang_CCMS_Handbook-Preface"></a>Preface</h1></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="idp18735264"></a>1. Document Conventions</h2></div></div></div><div class="para">
This manual uses several conventions to highlight certain words and phrases and draw attention to specific pieces of information.
</div><div class="para">
In PDF and paper editions, this manual uses typefaces drawn from the <a href="https://fedorahosted.org/liberation-fonts/" target="_top">Liberation Fonts</a> set. The Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the Liberation Fonts set by default.
</div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idp18738144"></a>1.1. Typographic Conventions</h3></div></div></div><div class="para">
Four typographic conventions are used to call attention to specific words and phrases. These conventions, and the circumstances they apply to, are as follows.
</div><div class="para">
<code class="literal">Mono-spaced Bold</code>
</div><div class="para">
Used to highlight system input, including shell commands, file names and paths. Also used to highlight keys and key combinations. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
To see the contents of the file <code class="filename">my_next_bestselling_novel</code> in your current working directory, enter the <code class="command">cat my_next_bestselling_novel</code> command at the shell prompt and press <span class="keycap"><strong>Enter</strong></span> to execute the command.
</div></blockquote></div><div class="para">
The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all distinguishable thanks to context.
</div><div class="para">
Key combinations can be distinguished from an individual key by the plus sign that connects each part of a key combination. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
Press <span class="keycap"><strong>Enter</strong></span> to execute the command.
</div><div class="para">
Press <span class="keycap"><strong>Ctrl</strong></span>+<span class="keycap"><strong>Alt</strong></span>+<span class="keycap"><strong>F2</strong></span> to switch to a virtual terminal.
</div></blockquote></div><div class="para">
The first example highlights a particular key to press. The second example highlights a key combination: a set of three keys pressed simultaneously.
</div><div class="para">
If source code is discussed, class names, methods, functions, variable names and returned values mentioned within a paragraph will be presented as above, in <code class="literal">mono-spaced bold</code>. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
File-related classes include <code class="classname">filesystem</code> for file systems, <code class="classname">file</code> for files, and <code class="classname">dir</code> for directories. Each class has its own associated set of permissions.
</div></blockquote></div><div class="para">
<span class="application"><strong>Proportional Bold</strong></span>
</div><div class="para">
This denotes words or phrases encountered on a system, including application names; dialog box text; labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
Choose <span class="guimenu"><strong>System</strong></span> → <span class="guisubmenu"><strong>Preferences</strong></span> → <span class="guimenuitem"><strong>Mouse</strong></span> from the main menu bar to launch <span class="application"><strong>Mouse Preferences</strong></span>. In the <span class="guilabel"><strong>Buttons</strong></span> tab, click the <span class="guilabel"><strong>Left-handed mouse</strong></span> check box and click <span class="guibutton"><strong>Close</strong></span> to switch the primary mouse button from the left to the right (making the mouse suitable for use in the left hand).
</div><div class="para">
To insert a special character into a <span class="application"><strong>gedit</strong></span> file, choose <span class="guimenu"><strong>Applications</strong></span> → <span class="guisubmenu"><strong>Accessories</strong></span> → <span class="guimenuitem"><strong>Character Map</strong></span> from the main menu bar. Next, choose <span class="guimenu"><strong>Search</strong></span> → <span class="guimenuitem"><strong>Find…</strong></span> from the <span class="application"><strong>Character Map</strong></span> menu bar, type the name of the character in the <span class="guilabel"><strong>Search</strong></span> field and click <span class="guibutton"><strong>Next</strong></span>. The character you sought will be highlighted in the <span class="guilabel"><strong>Character Table</strong></span>. Double-click this highlighted character to place it in the <span class="guilabel"><strong>Text to copy</strong></span> field and then click the <span class="guibutton"><strong>Copy</strong></span> button. Now switch back to your document and choose <span class="guimenu"><strong>Edit</strong></span> → <span class="guimenuitem"><strong>Paste</strong></span> from the <span class="application"><strong>gedit</strong></span> menu bar.
</div></blockquote></div><div class="para">
The above text includes application names; system-wide menu names and items; application-specific menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all distinguishable by context.
</div><div class="para">
<code class="command"><em class="replaceable"><code>Mono-spaced Bold Italic</code></em></code> or <span class="application"><strong><em class="replaceable"><code>Proportional Bold Italic</code></em></strong></span>
</div><div class="para">
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable text. Italics denotes text you do not input literally or displayed text that changes depending on circumstance. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
To connect to a remote machine using ssh, type <code class="command">ssh <em class="replaceable"><code>username</code></em>@<em class="replaceable"><code>domain.name</code></em></code> at a shell prompt. If the remote machine is <code class="filename">example.com</code> and your username on that machine is john, type <code class="command">ssh john@example.com</code>.
</div><div class="para">
The <code class="command">mount -o remount <em class="replaceable"><code>file-system</code></em></code> command remounts the named file system. For example, to remount the <code class="filename">/home</code> file system, the command is <code class="command">mount -o remount /home</code>.
</div><div class="para">
To see the version of a currently installed package, use the <code class="command">rpm -q <em class="replaceable"><code>package</code></em></code> command. It will return a result as follows: <code class="command"><em class="replaceable"><code>package-version-release</code></em></code>.
</div></blockquote></div><div class="para">
Note the words in bold italics above — username, domain.name, file-system, package, version and release. Each word is a placeholder, either for text you enter when issuing a command or for text displayed by the system.
</div><div class="para">
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and important term. For example:
</div><div class="blockquote"><blockquote class="blockquote"><div class="para">
Publican is a <em class="firstterm">DocBook</em> publishing system.
</div></blockquote></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idp17449520"></a>1.2. Pull-quote Conventions</h3></div></div></div><div class="para">
Terminal output and source code listings are set off visually from the surrounding text.
</div><div class="para">
Output sent to a terminal is set in <code class="computeroutput">mono-spaced roman</code> and presented thus:
</div><pre class="screen">books Desktop documentation drafts mss photos stuff svn
books_tests Desktop1 downloads images notes scripts svgs</pre><div class="para">
Source-code listings are also set in <code class="computeroutput">mono-spaced roman</code> but add syntax highlighting as follows:
</div><pre class="programlisting">package org.<span class="perl_Function">jboss</span>.<span class="perl_Function">book</span>.<span class="perl_Function">jca</span>.<span class="perl_Function">ex1</span>;
<span class="perl_Keyword">import</span> javax.naming.InitialContext;
<span class="perl_Keyword">public</span> <span class="perl_Keyword">class</span> ExClient
{
<span class="perl_Keyword">public</span> <span class="perl_DataType">static</span> <span class="perl_DataType">void</span> <span class="perl_Function">main</span>(String args[])
<span class="perl_Keyword">throws</span> Exception
{
InitialContext iniCtx = <span class="perl_Keyword">new</span> InitialContext();
Object ref = iniCtx.<span class="perl_Function">lookup</span>(<span class="perl_String">"EchoBean"</span>);
EchoHome home = (EchoHome) ref;
Echo echo = home.<span class="perl_Function">create</span>();
System.<span class="perl_Function">out</span>.<span class="perl_Function">println</span>(<span class="perl_String">"Created Echo"</span>);
System.<span class="perl_Function">out</span>.<span class="perl_Function">println</span>(<span class="perl_String">"Echo.echo('Hello') = "</span> + echo.<span class="perl_Function">echo</span>(<span class="perl_String">"Hello"</span>));
}
}</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="idp20265904"></a>1.3. Notes and Warnings</h3></div></div></div><div class="para">
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
</div><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should have no negative consequences, but you might miss out on a trick that makes your life easier.
</div></div></div><div class="important"><div class="admonition_header"><p><strong>Important</strong></p></div><div class="admonition"><div class="para">
Important boxes detail things that are easily missed: configuration changes that only apply to the current session, or services that need restarting before an update will apply. Ignoring a box labeled 'Important' will not cause data loss but may cause irritation and frustration.
</div></div></div><div class="warning"><div class="admonition_header"><p><strong>Warning</strong></p></div><div class="admonition"><div class="para">
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
</div></div></div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="sect_RedHat-Getting_Help_and_Giving_Feedback"></a>2. Getting Help and Giving Feedback</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sect_RedHat-Do_You_Need_Help"></a>2.1. Do You Need Help?</h3></div></div></div><a id="idp30950784" class="indexterm"></a><div class="para">
If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer Portal at <a href="http://access.redhat.com" target="_top">http://access.redhat.com</a>. Through the customer portal, you can:
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
search or browse through a knowledgebase of technical support articles about Red Hat products.
</div></li><li class="listitem"><div class="para">
submit a support case to Red Hat Global Support Services (GSS).
</div></li><li class="listitem"><div class="para">
access other product documentation.
</div></li></ul></div><div class="para">
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and technology. You can find a list of publicly available mailing lists at <a href="https://www.redhat.com/mailman/listinfo" target="_top">https://www.redhat.com/mailman/listinfo</a>. Click on the name of any mailing list to subscribe to that list or to access the list archives.
</div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="sect-RedHat-We_Need_Feedback"></a>2.2. We Need Feedback</h3></div></div></div><a id="idp17438016" class="indexterm"></a><div class="para">
If you find a typographical error in this manual, or if you have thought of a way to make this manual better, we would love to hear from you. Please submit a report in Bugzilla: <a href="http://bugzilla.redhat.com/" target="_top">http://bugzilla.redhat.com/</a> against the product <span class="application"><strong>PressGang CCMS.</strong></span>
</div><div class="para">
When submitting a bug report, be sure to mention the manual's identifier: <em class="citetitle">PressGang_CCMS_Handbook</em>
</div><div class="para">
If you have a suggestion for improving the documentation, try to be as specific as possible when describing it. If you have found an error, please include the section number and some of the surrounding text so we can find it easily.
</div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="chap-Introduction"></a>Chapter 1. Introduction</h1></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#About_This_Guide">1.1. About This Guide</a></span></dt><dt><span class="section"><a href="#About_PressGang_CCMS">1.2. About PressGang CCMS</a></span></dt><dt><span class="section"><a href="#Known_Issues_and_Limitations">1.3. Known Issues and Limitations</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="About_This_Guide"></a>1.1. About This Guide</h2></div></div></div><div class="para">
This guide is intended to be a handbook for document designers, writers, illustrators, and translators using PressGang CCMS. If something is missing or is inaccurate, please use the <em class="citetitle">Report a Bug</em> link in the topic in question, or near where you think the content should be, to report the issue.
</div><div class="formalpara"><div class="title">Live Book</div>
This book is editable. Browse to the DocBuilder Editor interface for this book at <a href="http://docbuilder.usersys.redhat.com/13968/" target="_top">http://docbuilder.usersys.redhat.com/13968/</a> and use the <span class="guibutton"><strong>Edit This Topic</strong></span> link to edit a topic.
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=13976" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+13976-478230+%5BLatest%5D&cf_build_id=13976-478230+16+Jul+2013+19%3A04+en-US+%5BLatest%5D&comment=Title%3A+About+This+Guide%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="About_PressGang_CCMS"></a>1.2. About PressGang CCMS</h2></div></div></div><div class="para">
PressGang CCMS is a <em class="firstterm">Component Content Management System (CCMS)</em> written in Java EE 6 and deployable to JBoss Enterprise Application Platform 6. PressGang CCMS is in active development by the Red Hat Engineering Content Services (ECS) Tools Team.
</div><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
PressGang CCMS is not a Content Management System (CMS), like Drupal or MediaWiki. A CMS manages published content like wiki articles or blogs, but a CCMS manages the building blocks for content.
</div></div></div><div class="para">
PressGang CCMS is only one part of the toolchain used by Red Hat Content Services. It works in conjunction with another tool called Publican. Publican is the tool used to build human-readable outputs such as HTML and PDF from Docbook.
</div><div class="formalpara"><div class="title">History</div>
In the early days of content authoring at Red Hat, the team started out by using SGML and Makefiles. The next step was to develop Publican, which greatly simplified the publication process and allowed for localization.
</div><div class="para">
The first attempt at topic reuse was a tool called <code class="code">Topic Tool</code>. It was a prototype system that used Docbook's <code class="sgmltag-element"><xi:include></code> tag to build up modular documentation. In reality it was difficult to use and maintain.
</div><div class="para">
PressGang CCMS simplifies the toolchain, and makes topic reuse and modular documentation more feasible.
</div><div class="formalpara"><div class="title">Competition</div>
PressGang CCMS is not the first or only Component Content Management System. Here are some of its main competitors:
</div><div class="table"><a id="idp17100256"></a><p class="title"><strong>Table 1.1. </strong></p><div class="table-contents"><table summary=""><colgroup><col width="25%" /><col width="25%" /><col width="25%" /><col width="25%" /></colgroup><thead><tr><th class="">
Product Name
</th><th class="">
License and Cost
</th><th class="">
DTDs
</th><th class="">
Description
</th></tr></thead><tbody><tr><td class="">
<div class="para">
Vasont
</div>
</td><td class="">
<div class="para">
Commercial, USD$30,000+/year
</div>
</td><td class="">
Docbook, DITA
</td><td class="">
<div class="para">
Vasont is probably the largest CCMS out there. It costs millions of dollars per year to deploy and maintain. Vasont is used by huge outsourcing firms.
</div>
</td></tr><tr><td class="">
<div class="para">
Arbortext
</div>
</td><td class="">
<div class="para">
Proprietary, USD$10,000+/year
</div>
</td><td class="">
<div class="para">
DITA
</div>
</td><td class="">
<div class="para">
Arbortext includes an editor, illustrator, and other types of tools, as well as an overarching documentation management system. It is used by IBM, among others. Arbortext supports DITA only, so there is an additional conversion cost to move from Docbook to DITA.
</div>
</td></tr><tr><td class="">
<div class="para">
Componize
</div>
</td><td class="">
<div class="para">
Proprietary, unknown per-user
</div>
</td><td class="">
<div class="para">
DITA
</div>
</td><td class="">
<div class="para">
Componize is a CCMS built atop the Alfresco CMS. The information available about it is pretty sparse.
</div>
</td></tr><tr><td class="">
<div class="para">
Author-IT
</div>
</td><td class="">
<div class="para">
Proprietary, USD$36,000+/yearr
</div>
</td><td class="">
<div class="para">
DITA
</div>
</td><td class="">
<div class="para">
Author-IT supports most of what ECS would need, at a stiff ongoing price point. Author-IT supports DITA only, so there is an additional conversion cost to move from Docbook to DITA.
</div>
</td></tr><tr><td class="">
<div class="para">
Calenco
</div>
</td><td class="">
<div class="para">
Open Source, $8000+/year, plus significant development and maintenance costs in the long term
</div>
</td><td class="">
<div class="para">
Docbook, DITA
</div>
</td><td class="">
<div class="para">
We first became aware of Calenco in May 2012. We were very excited about it because it promised to do everything we were trying to do with PressGang CCMS, including translation and image management. In 2012, we were only able to see the "Developer Version", which is not only open-source, but also free-as-in-beer. This version is missing too much functionality to be a contender.
</div>
<div class="para">
In April 2013 we undertook an evaluation of Calenco XML CMS. It was found to underperform PressGang CCMS significantly, and lacked the flexibility needed for Red Hat's workflow. It also has a mixed license model which is not appealing. Certain parts of Calenco are open source, but others are proprietary, and are licensed from a company called XML Mind. If we wanted to go this route, we could license the components directly as well.
</div>
</td></tr></tbody></table></div></div><br class="table-break" /><div class="para">
Rather than spend thousands of dollars per year on a proprietary system, with huge content-conversion and re-tooling costs, we have built PressGang CCMS. The goal is to release it into the community using the same model as Publican, so that others can receive the same benefit that Red Hat is already receiving from it.
</div><div class="para">
PressGang CCMS may not be the final solution. It is impossible to know what Red Hat will be using to manage documentation in 5 or 10 years. But PressGang CCMS is the next step, to enable Content Services to scale with Red Hat's growth and to produce great documentation efficiently.
</div><div class="formalpara"><div class="title">Purpose</div>
PressGang CCMS was created to solve some specific problems within Content Services, and also to provide some major benefits.
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
The first goal of PressGang CCMS was to enable topic reuse. As Red Hat grows its product line, and the work load of ECS grows, it is clear that we need a way to reuse relevant content between multiple groups. Even if content is reused only once, it is still an increase in efficiency. With the approach that Red Hat takes toward product layering and interoperability, it is clear that topic reuse is something that will benefit all of us.
</div></li><li class="listitem"><div class="para">
This is even more obvious in the area of localization. PressGang CCMS provides an easy way to push and pull strings from the Zanata Translation Management System, and also allows Zanata's translation memory to be used more effectively on new content. This results in content which is already partially translated before formal translation is even begun.
</div></li><li class="listitem"><div class="para">
Another goal was toolchain simplification. Red Hat's products are complex enough for new writers to understand, without having to also learn and understand Fedora, RHEL, Docbook, Publican, Subversion, Git, CVS, Brew, RHPkg right away as well. PressGang CCMS gives writers a faster route to productivity. The paradigm of a web-based UI is a very familiar one, and significantly eases the learning curve. This gives writers more bandwidth to learn about the products they will be documenting, and means that they spend more of their time doing the writing that they actually want to do. Writers will still have lots of opportunities to increase their technical skills, but they don't need to do it just to get started.
</div></li><li class="listitem"><div class="para">
Planning, scoping, and gap analysis are easier to manage with good reporting tools at our disposal. With PressGang CCMS, it is easy to get information about which types of topics are present and absent in documentation, how much writing actually goes into a given release, and how realistic an initial documentation plan actually was, after the fact. The amount of trackable data is huge. Some of the questions that can easily be answered are:
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
How many topics were created/updated/reviewed this week?
</div></li><li class="listitem"><div class="para">
Have we met our commitments for this release?
</div></li><li class="listitem"><div class="para">
Do we have any topics about securing the REST interfaces in EAP?
</div></li><li class="listitem"><div class="para">
How much can a team of three people be expected to write in a 6-month period?
</div></li><li class="listitem"><div class="para">
Which book has the most bugs logged against it?
</div></li></ul></div></li><li class="listitem"><div class="para">
We need to be able to remix existing content for new formats or audiences. What if we start out with a small product with a few security concerns in a User Guide, but eventually the product grows to the point that we need a dedicated Security Guide? With books in Subversion, this may become an exercise in regular expressions, copy, and paste. With the PressGang CCMS, this is a matter of searching for security topics related to Product X, and asking the CCMS to create a new content specification including the results of the search. The content specification can now be organized as appropriate.
</div><div class="para">
The above example actually happened, very recently. The Security Guide took a couple of hours to reorganize and publish to an internal staging site. It was able to be reviewed before lunch time of the same day it was started.
</div></li><li class="listitem"><div class="para">
We need to work with several different upstreams. We can't guarantee that an external team will use Subversion, Git, or another specific system. We can't even guarantee that they will use Docbook. We need a system that lets us add functionality when we need it, so that we can react quickly to changing business environments.
</div></li></ul></div><div class="formalpara"><div class="title">Architecture</div>
PressGang CCMS consists of several different components which work together. These are the web-based user interface (the UI), the REST API, a database to hold information about topics, a command-line tool called the CSProcessor, an integrated instance of the BIRT open-source reporting tool, and the DocBuilder continuous-intergration server. These components will be explained in detail later in this guide, but here is a quick overview of each.
</div><div class="variablelist"><dl class="variablelist"><dt><span class="term">UI</span></dt><dd><div class="para">
The UI is the most common entry-point to using the CCMS. It includes facilities for creating, updating, viewing, and searching for topics and content specifications. It is accessed via a web browser. The UI is the way that most writers will interact with the CCMS.
</div></dd><dt><span class="term">REST API</span></dt><dd><div class="para">
A REST API is a way of interacting with a web service by passing specific URLs and parsing the results. This is a very common way to interact with web-based applications. The PressGang CCMS uses a REST API to pull together all of its different components, such as the database and the UI.
</div><div class="para">
The REST API also allows other applications, services, and scripts to be built to extend the functionality of the CCMS. One such extension is the PressStar editor (<a href="https://github.com/jwulf/press-star" target="_top">https://github.com/jwulf/press-star</a>, which was built using the <code class="code">Node.JS</code> JavaScript library. The REST API gives the CCMS the ability to grow and change with the needs of Red Hat.
</div></dd><dt><span class="term">WebDAV</span></dt><dd><div class="para">
Topics are exposed via a WebDAV filesystem, which can be mounted as a drive in any modern operating system, and allows topics to be edited with regular text editors.
</div></dd><dt><span class="term">Database</span></dt><dd><div class="para">
PressGang uses a MySQL database to store all topics, content specifications, metadata, and revision history information. The important thing about this is that it is a relational database (RDBMS). Although it is using MySQL at the moment, it is not tied to any specific RDBMS.
</div></dd><dt><span class="term">CSProcessor</span></dt><dd><div class="para">
The basic organizational structure of a book built using PressGang CCMS is a content specification map. Currently this map is a plain-text file with special syntax. Content specifications are created and updated using a command-line tool called the CSProcessor. This tool is also used to create the payload which will be built into a book using Publican. In the future, the CSProcessor will be replaced or augmented by a web-based tool. The CSProcessor is used by documentation designers to create and organize the structure of books.
</div></dd><dt><span class="term">DocBuilder</span></dt><dd><div class="para">
The DocBuilder is a continuous-integration service which rebuilds content specifications at a regular interval. It is used by different teams for different reasons. Writers use it to preview their work and to collaborate with external teams. Translators use it to view content as they are translating it. The DocBuilder only builds books that have been registered with it. It is much faster and more flexible than the official documentation stage, but it does not output books in exactly the way that customers will see them.
</div><div class="para">
One advantage to the DocBuilder is that its output can be customized to be useful to a particular team, such as translators, QE, or Product Management.
</div></dd><dt><span class="term">BIRT Reporting Framework</span></dt><dd><div class="para">
BIRT is an open source reporting framework. The PressGang CCMS includes an integrated BIRT instance, which provides reports about topics, books, releases, and teams. BIRT is flexible enough to be able to provide a wide range of different types of reports.
</div></dd><dt><span class="term">PressGang CCMS Virtual Application</span></dt><dd><div class="para">
The Virtual Application is a VM built with VirtualBox that includes all the CCMS components in a single, isolated, ready-to-run environment. It was created to enable external parties to experiment and build upon the base platform. An example of this are university students using the CCMS and its content as the basis for language processing projects.
</div></dd></dl></div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=13979" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+13979-464344+%5BLatest%5D&cf_build_id=13979-464344+18+Jun+2013+15%3A43+en-US+%5BLatest%5D&comment=Title%3A+About+PressGang+CCMS%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="Known_Issues_and_Limitations"></a>1.3. Known Issues and Limitations</h2></div></div></div><div class="para">
PressGang CCMS provides a lot of benefits to document designers, writers, illustrators, and designers. However, it is not (yet) perfect.
</div><div class="formalpara"><div class="title">Providing Feedback</div>
If you notice a problem or have an idea for how the CCMS can be improved, please provide feedback. You can do this in a few different ways.
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
File a bug in Bugzilla, using the <em class="citetitle">PressGang CCMS</em> product. You can do this easily by clicking the <span class="guibutton"><strong>Report a Bug</strong></span> button at the left side of the web-based UI of PressGang CCMS.
</div></li><li class="listitem"><div class="para">
View or edit the context-sensitive Help on each page of the PressGang CCMS UI, by clicking the <span class="guilabel"><strong>Help</strong></span> link at the bottom of the page.
</div></li><li class="listitem"><div class="para">
Participate in a short survey about how to improve a specific part of the web-based UI of PressGang CCMS, by clicking the <span class="guilabel"><strong>Feedback</strong></span> link at the bottom of each page.
</div></li><li class="listitem"><div class="para">
Participate in discussions on the <code class="systemitem">#ccms-users</code> IRC channel.
</div></li></ul></div><div class="formalpara"><div class="title">Known Issues and Limitations</div>
The PressGang CCMS team is aware of the following issues. Workarounds are provided where relevant.
</div><div class="variablelist"><dl class="variablelist"><dt><span class="term">Author Group Information for Public Consumption</span></dt><dd><div class="para">
If writers are not correctly assigned to topics, the CCMS inserts a default user of "SkyNet Alpha Build System". This placeholder is not suitable for public documents.
</div><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
The following processes are work around methods until https://bugzilla.redhat.com/show_bug.cgi?id=981118 is implemented.
</div></div></div><div class="para">
To add a writer by name, follow these steps:
</div><div class="orderedlist"><ol><li class="listitem"><div class="para">
Assign a registered CCMS user (writer) to a topic.
</div></li><li class="listitem"><div class="para">
On the Extended Properties tab of each topic, add the First Name and Last Name fields.
</div></li><li class="listitem"><div class="para">
In each topic, add the actual writer's first and last name to the fields.
</div></li></ol></div><div class="para">
To add a Red Hat Documentation Group author:
</div><div class="orderedlist"><ol><li class="listitem"><div class="para">
Assign a registered CCMS user to a topic.
</div></li><li class="listitem"><div class="para">
On the Extended Properties tab of the topic, add the First Name and Last Name fields.
</div></li><li class="listitem"><div class="para">
Add the string <code class="literal">Red&nbsp;Hat Documentation Group</code> to the Last Name field.
</div><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
Adding this string to the last name field ensures the string is not reordered when translated to languages such as Japanese.
</div></div></div></li></ol></div></dd><dt><span class="term">Limited Support for Docbook 5 Topics</span></dt><dd><div class="para">
Topics were only recently introduced as a DocBook element in version 5.1, and Docbook 5 is not officially supported by Publican 3 (see <a href="https://bugzilla.redhat.com/show_bug.cgi?id=697367" target="_top">BZ#697367</a>). Section elements have been used to emulate a topic, but this has led to a number of limitations, many of which are listed below.
</div></dd><dt><span class="term">Entity files need to be stored separately.</span></dt><dd><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
This problem is a very low priority, because the usage of entities, beyond the ones required by some Red Hat Publican brands, is discouraged within ECS. Entities create problems with translation and content reuse.
</div></div></div><div class="para">
The CCMS does not yet have a mechanism for storing or updating entity files (typically <code class="filename"><em class="replaceable"><code>book_name</code></em>.ent</code>). To work around this issue, you can store the entity files in an external filesystem (and back them up in a VCS), and direct the <code class="code">csprocessor</code> command to include them at build time. This problem will be fixed at a later date.
</div></dd><dt><span class="term">Topics cannot include nested <section> elements</span></dt><dd><div class="para">
Because the CCMS adds some content to the end of each topic (such as the <span class="guilabel"><strong>Report a Bug</strong></span> links), allowing nested <section> elements causes validation errors.
</div><div class="para">
This is easy to work around. Make the top-level section for each level a <code class="literal">Section:</code> in the content specification, rather than a separate topic. In this way, you can nest as deeply as necessary.
</div></dd><dt><span class="term">Real-time "help desk" support is not available.</span></dt><dd><div class="para">
The entire ECS Tools team works in Brisbane, and are only available to answer questions during that time. To work around this limitation, use Bugzilla or one of the other feedback mechanisms mentioned above to ask questions and provide feedback.
</div><div class="para">
As a workaround, you can contact one of the following people if you are unable to work within the CCMS, and they may be able to resolve the issue for you.
</div><div class="table"><a id="idp7154208"></a><p class="title"><strong>Table 1.2. PressGang CCMS Contacts</strong></p><div class="table-contents"><table summary="PressGang CCMS Contacts"><colgroup><col width="33%" /><col width="33%" /><col width="33%" /></colgroup><thead><tr><th class="">
Name
</th><th class="">
Email
</th><th class="">
Location
</th></tr></thead><tbody><tr><td class="">
Steve Gordon
</td><td class="">
sgordon@redhat.com
</td><td class="">
Canada
</td></tr><tr><td class="">
Sneha Agarwal
</td><td class="">
snagarwa@redhat.com
</td><td class="">
Pune
</td></tr><tr><td class="">
Aakanksha Singh
</td><td class="">
aasingh@redhat.com
</td><td class="">
Pune
</td></tr><tr><td class="">
Petr Penicka
</td><td class="">
ppenicka@redhat.com
</td><td class="">
Brno
</td></tr></tbody></table></div></div><br class="table-break" /></dd><dt><span class="term">Rapid pace of UI changes.</span></dt><dd><div class="para">
The new UI is still in active development and is subject to change. Each time the UI gets an update, a notice of the changes is published to its welcome screen. In addition, emails are sent out when upgrades are scheduled and have occurred.
</div><div class="para">
As a workaround, you have the choice to use the stable interface or the PressGang.Next interface. The stable interface is updated much less frequently and is known to be stable.
</div></dd><dt><span class="term">This document is incomplete.</span></dt><dd><div class="para">
This document, like the CCMS, is a work in progress. Feedback and corrections are appreciated.
</div></dd></dl></div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=13997" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+13997-474710+%5BLatest%5D&cf_build_id=13997-474710+08+Jul+2013+16%3A03+en-US+%5BLatest%5D&comment=Title%3A+Known+Issues+and+Limitations%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="chap-Topic-Based_Authoring_in_the_CCMS"></a>Chapter 2. Topic-Based Authoring in the CCMS</h1></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#About_Topic-Based_Authoring1">2.1. About Topic-Based Authoring</a></span></dt><dt><span class="section"><a href="#sect-Topic_Types">2.2. Topic Types</a></span></dt><dd><dl><dt><span class="section"><a href="#Content">2.2.1. Concept</a></span></dt><dt><span class="section"><a href="#Task3">2.2.2. Task</a></span></dt><dt><span class="section"><a href="#Reference4">2.2.3. Reference</a></span></dt><dt><span class="section"><a href="#CSProcessor_Map">2.2.4. CSProcessor Map</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Metadata">2.3. Metadata</a></span></dt><dd><dl><dt><span class="section"><a href="#Per-Topic_Metadata">2.3.1. Per-Topic Metadata</a></span></dt><dt><span class="section"><a href="#Per-Map_Metadata">2.3.2. Per-Map Metadata</a></span></dt></dl></dd></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="About_Topic-Based_Authoring1"></a>2.1. About Topic-Based Authoring</h2></div></div></div><div class="para">
<em class="firstterm">Topic-based authoring</em> is a methodology for distilling content into <em class="firstterm">topics</em>, which can stand somewhat on their own, and then building a document out of these topics. Topic-based authoring is different from <em class="firstterm">narrative authoring</em>, which assumes that a book or article will be read cover-to-cover.
</div><div class="para">
<em class="firstterm">Darwin Information Typing Architecture (DITA)</em> is the most well-known paradigm for topic-based authoring. Red Hat has borrowed some of the principles of DITA while retaining the Docbook DTD, which provides for a more mature toolchain and richer markup language.
</div><div class="formalpara"><div class="title">Relationship between PressGang CCMS and Topic-Based Authoring</div>
PressGang CCMS does not force a topic-based approach, and a topic-based approach can be used outside the scope of PressGang CCMS. However, the CCMS was designed with a topic-based approach in mind, and works well with this approach.
</div><div class="table"><a id="idp18636352"></a><p class="title"><strong>Table 2.1. Topic-Based vs Narrative Writing</strong></p><div class="table-contents"><table summary="Topic-Based vs Narrative Writing"><colgroup><col width="50%" /><col width="50%" /></colgroup><thead><tr><th class="">
Topic-Based
</th><th class="">
Narrative
</th></tr></thead><tbody><tr><td class="">
<div class="para">
Assumes readers may enter the document at any point
</div>
</td><td class="">
<div class="para">
Assumes readers will start at the beginning and work their way through the book or article
</div>
</td></tr><tr><td class="">
<div class="para">
Allows for repetition of key content at the places in the document where they are needed, without increasing document maintenance
</div>
</td><td class="">
<div class="para">
Uses copy-and-paste or cross-linking for content that is relevant in different areas of the same content
</div>
</td></tr><tr><td class="">
<div class="para">
Allows existing content to be "remixed" into different formats depending on the audience or other factors
</div>
</td><td class="">
<div class="para">
Restructuring of a document requires a lot of work
</div>
</td></tr><tr><td class="">
<div class="para">
Provides for different topic types which have different structures and rules (concept, task, and reference)
</div>
</td><td class="">
<div class="para">
Treats all content the same, because it's basically all words, right?
</div>
</td></tr><tr><td class="">
<div class="para">
Makes it easy for multiple people (and teams) to share and work on common content together, because each "work unit" is small and relatively self-contained
</div>
</td><td class="">
<div class="para">
Typically, one person will own one chapter or one book, because this makes for minimal editing conflicts. This makes it harder to share and review work.
</div>
</td></tr><tr><td class="">
<div class="para">
Because units of documentation are smaller, bugs can be filed right where the problems are.
</div>
</td><td class="">
<div class="para">
Bugs are filed on a per-book basis, with only the bug-filer's description to guide the writer about where to find and fix the problem.
</div>
</td></tr></tbody></table></div></div><br class="table-break" /><div class="para">
These are only a few of the benefits of topic-based authoring. For more information, refer to <a href="http://en.wikipedia.org/wiki/Topic-based_authoring" target="_top">http://en.wikipedia.org/wiki/Topic-based_authoring</a>.
</div><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
It is easy to lose sight of the reader, in the zeal for the topic-based approach. The idea of attempting to categorize content into topic types does not work equally well for all kinds of content, and the judgment of the writer, when thinking about the reader, is the ultimate guide. Sometimes a task needs to have some information in it that looks conceptual, and sometimes a concept needs to have more information than a simple dictionary definition. A task may not always look like a procedure, but sometimes it may look like an illustrated example or a workflow. When categorizing topics, use your judgment. When segmenting content into topics, think about the unit of granularity that makes the most sense for reuse, not the smallest granularity possible.
</div></div></div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=14023" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+14023-457502+%5BLatest%5D&cf_build_id=14023-457502+05+Jun+2013+15%3A28+en-US+%5BLatest%5D&comment=Title%3A+About+Topic-Based+Authoring%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="sect-Topic_Types"></a>2.2. Topic Types</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Content"></a>2.2.1. Concept</h3></div></div></div><div class="para">
A <em class="firstterm">concept</em>, in terms of topic-based writing, is explanatory material about something. It is a definition, but contains additional information. A concept may talk about a single thing, or a relationship between things or overview of a thing. A concept often answers the question "What is _____?", but continues on to answer "Why should I care?"
</div><div class="para">
Separating concepts from their associated tasks and references provides a natural separation for a reader between the "What", "Why", "How", and "What Else" questions which are addressed in technical documentation. This separation provides the reader with the confidence that comes with understanding what's involved before jumping into a task.
</div><div class="para">
At Red Hat, topics usually have titles that start with the word <em class="wordasword"> About </em>. Here are some examples.
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
About Encryption
</div></li><li class="listitem"><div class="para">
About Component Content Management Systems
</div></li><li class="listitem"><div class="para">
About Bedsheets
</div></li><li class="listitem"><div class="para">
About the Components of a Service-Oriented Architecture
</div></li></ul></div><div class="para">
Concepts can contain paragraphs, images, and other types of explanatory content.
</div><div class="formalpara"><div class="title">Granularity of Concepts</div>
A common trap that people fall into with regard to concepts is making them too granular. Make sure that your concept represents a complete and useful idea to the user. When Red Hat first embarked on the topic-based authoring journey, we attempted to be extremely pure-minded about the content of a concept, and the result was often choppy prose. Over time, these choppy contents are often being merged together into units that make more sense as standalone, reusable units. Conditional statements assist in making concepts more universal without sacrificing cohesion of content. The writer's judgment on behalf of the reader is always the final decider.
</div><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
This topic itself is a concept.
</div></div></div><div class="example"><a id="idp22388944"></a><p class="title"><strong>Example 2.1. XML Example for a Concept</strong></p><div class="example-contents"><pre class="programlisting">
<span class="perl_Keyword"><section></span>
<span class="perl_Keyword"><title></span>Example Concept<span class="perl_Keyword"></title></span>
<span class="perl_Keyword"><para></span>
This is an very simple concept with a single paragraph. A real concept might have images, tables, lists, or other content as appropriate.
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></section></span>
</pre></div></div><br class="example-break" /><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=14000" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+14000-457484+%5BLatest%5D&cf_build_id=14000-457484+05+Jun+2013+15%3A27+en-US+%5BLatest%5D&comment=Title%3A+Concept%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Task3"></a>2.2.2. Task</h3></div></div></div><div class="para">
A task is a topic that answers the question "How?" for the reader. In Docbook, a task is usually either a <code class="sgmltag-element"><procedure></code>, although sometimes it may be a series of code snippets with explanatory material or an image with explanatory information, such as a workflow or diagram. In published output, a <code class="sgmltag-element"><procedure></code> is rendered as a numbered list, with optional subtasks or alternative steps.
</div><div class="para">
The title of a task starts with a verb. "Wash a Car" is preferrable to "How to Wash a Car" or "Washing a Car" as a title. Below are some examples of tasks.
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
Make a Bed
</div></li><li class="listitem"><div class="para">
Install JBoss Enterprise Application Platform 6
</div></li><li class="listitem"><div class="para">
Brew Good Coffee
</div></li><li class="listitem"><div class="para">
Configure Apache HTTPD Server
</div></li></ul></div><div class="para">
A task often includes an introduction which contextualizes it in the mind of the reader, a list of prerequisites (which may be links to other tasks), and a result statement, which describes the result of performing the task.
</div><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
Often, a task is the thing that you start out to document. Along the way, you realize that you need some supporting concepts and references to go along with it. A great way to start a documentation plan is to list all of the tasks that need to be documented.
</div></div></div><div class="example"><a id="idp6160880"></a><p class="title"><strong>Example 2.2. Example XML for a Task</strong></p><div class="example-contents"><pre class="programlisting">
<span class="perl_Keyword"><section></span>
<span class="perl_Keyword"><title></span>Example Procedure<span class="perl_Keyword"></title></span>
<span class="perl_Keyword"><para></span>
This is the introduction to the procedure.
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"><itemizedlist></span>
<span class="perl_Keyword"><title></span>Prerequisites<span class="perl_Keyword"></title></span>
<span class="perl_Keyword"><listitem></span>
<span class="perl_Keyword"><para></span>This is the first prerequisite.<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></listitem></span>
<span class="perl_Keyword"><listitem></span>
<span class="perl_Keyword"><para></span>This is the second prerequisite.<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></listitem></span>
<span class="perl_Keyword"></itemizedlist></span>
<span class="perl_Keyword"><procedure></span>
<span class="perl_Keyword"><title></span>Example Procedure<span class="perl_Keyword"></title></span>
<span class="perl_Keyword"><step></span>
<span class="perl_Keyword"><para></span>
This is the first step.
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></step></span>
<span class="perl_Keyword"><step></span>
<span class="perl_Keyword"><para></span>
This is the second step, with a table of options and values to set, or something like that.
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"><table></span>
<span class="perl_Keyword"><title></span>Options for this step<span class="perl_Keyword"></title></span>
<span class="perl_Keyword"><tgroup</span><span class="perl_Others"> cols=</span><span class="perl_String">"2"</span><span class="perl_Keyword">></span>
<span class="perl_Keyword"><thead></span>
<span class="perl_Keyword"><row></span>
<span class="perl_Keyword"><entry></span>Name<span class="perl_Keyword"></entry></span>
<span class="perl_Keyword"><entry></span>Value<span class="perl_Keyword"></entry></span>
<span class="perl_Keyword"></row></span>
<span class="perl_Keyword"></thead></span>
<span class="perl_Keyword"><tbody></span>
<span class="perl_Keyword"><row></span>
<span class="perl_Keyword"><entry></span>theAnswer<span class="perl_Keyword"></entry></span>
<span class="perl_Keyword"><entry></span>42<span class="perl_Keyword"></entry></span>
<span class="perl_Keyword"></row></span>
<span class="perl_Keyword"><row></span>
<span class="perl_Keyword"><entry></span>hasTowel<span class="perl_Keyword"></entry></span>
<span class="perl_Keyword"><entry></span>1<span class="perl_Keyword"></entry></span>
<span class="perl_Keyword"></row></span>
<span class="perl_Keyword"></tbody></span>
<span class="perl_Keyword"></tbody></span>
<span class="perl_Keyword"></table></span>
<span class="perl_Keyword"></step></span>
<span class="perl_Keyword"><step></span>
<span class="perl_Keyword"><para></span>This step has some substeps. Follow them all.<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"><substeps></span>
<span class="perl_Keyword"><step></span>
<span class="perl_Keyword"><para></span>The first step<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></step></span>
<span class="perl_Keyword"><step></span>
<span class="perl_Keyword"><para></span>The second step<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></step></span>
<span class="perl_Keyword"></substeps></span>
<span class="perl_Keyword"></step></span>
<span class="perl_Keyword"><step></span>
<span class="perl_Keyword"><para></span>Choose one or the other of these alternative steps.<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"><stepalternatives></span>
<span class="perl_Keyword"><step></span>
<span class="perl_Keyword"><para></span>Install Linux.<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></step></span>
<span class="perl_Keyword"><step></span>
<span class="perl_Keyword"><para></span>Install Windows.<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></step></span>
<span class="perl_Keyword"></stepalternatives></span>
<span class="perl_Keyword"></step></span>
<span class="perl_Keyword"></procedure></span>
<span class="perl_Keyword"><formalpara></span>
<span class="perl_Keyword"><title></span>Result<span class="perl_Keyword"></title></span>
<span class="perl_Keyword"><para></span>
Optionally, you can describe the end-state of the procedure at the end.
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></formalpara></span>
<span class="perl_Keyword"></section></span>
</pre></div></div><br class="example-break" /><div class="para">
If a series of tasks must always be performed together and in the same order, consider combining them into a single topic with multiple tasks, or a single task with sub-tasks. This benefits the reader, but has an impact on reusability of the topic, so consider this design decision carefully.
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=14017" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+14017-457498+%5BLatest%5D&cf_build_id=14017-457498+05+Jun+2013+15%3A28+en-US+%5BLatest%5D&comment=Title%3A+Task%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Reference4"></a>2.2.3. Reference</h3></div></div></div><div class="para">
A reference includes extra information about a concept or task. A reference may consist of one or more tables or lists, detailed diagrams with call-outs, or well-commented standalone code examples. A reference's title format is not as rigid as that of a concept of a reference. Following are some examples of references.
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
Types of bedsheets
</div></li><li class="listitem"><div class="para">
Configuration options for Apache HTTPD
</div></li><li class="listitem"><div class="para">
Example WSDL Descriptor
</div></li><li class="listitem"><div class="para">
Included Authentication Modules
</div></li><li class="listitem"><div class="para">
RAID Level Reference
</div></li></ul></div><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
The differences between a concept and a reference can seem blurry. A good rule of thumb is that if the user needs to know it to even begin the related task, it is probably a concept. If it seems like extra information, it may be a reference. In practice, some topics could go either way.
</div></div></div><div class="example"><a id="idp7637120"></a><p class="title"><strong>Example 2.3. Example XML for a Reference</strong></p><div class="example-contents"><pre class="programlisting">
<span class="perl_Keyword"><section></span>
<span class="perl_Keyword"><title></span>Colors of the Rainbow<span class="perl_Keyword"></title></span>
<span class="perl_Keyword"><para></span>Although it may seem like there are an infinite number of colors in the rainbow, only seven are recognized.<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"><itemizedlist></span>
<span class="perl_Keyword"><listitem></span>
<span class="perl_Keyword"><para></span>
Red
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></listitem></span>
<span class="perl_Keyword"><listitem></span>
<span class="perl_Keyword"><para></span>
Orange
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></listitem></span>
<span class="perl_Keyword"><listitem></span>
<span class="perl_Keyword"><para></span>
Yellow
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></listitem></span>
<span class="perl_Keyword"><listitem></span>
<span class="perl_Keyword"><para></span>
Green
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></listitem></span>
<span class="perl_Keyword"><listitem></span>
<span class="perl_Keyword"><para></span>
Indigo
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></listitem></span>
<span class="perl_Keyword"><listitem></span>
<span class="perl_Keyword"><para></span>
Violet
<span class="perl_Keyword"></para></span>
<span class="perl_Keyword"></listitem></span>
<span class="perl_Keyword"></itemizedlist></span>
<span class="perl_Keyword"></section></span>
</pre></div></div><br class="example-break" /><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=14014" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+14014-457495+%5BLatest%5D&cf_build_id=14014-457495+05+Jun+2013+15%3A28+en-US+%5BLatest%5D&comment=Title%3A+Reference%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="CSProcessor_Map"></a>2.2.4. CSProcessor Map</h3></div></div></div><div class="para">
A CSProcessor map, also known as a <em class="firstterm">Content Specification</em>, or Content Spec for short, is actually not a type of topic in the topic-based authoring approach. Its closest analogue would be a DITA map. It is a top-level map used to structure a book. Currently, CSProcessor maps are stored as records in the PressGang CCMS database, just as topics are. This will be changing soon, however, and these maps will be stored as database objects.
</div><div class="para">
The storage mechanism for the CSProcessor maps is mostly an internal detail. The principle about how they work is much more interesting. Below is an example of a map in the text-based format. When the web UI is updated so that you can manage maps there, the principals will be the same, even if the mechanisms for working with maps change.
</div><div class="example"><a id="idp7649536"></a><p class="title"><strong>Example 2.4. Example CSProcessor Map</strong></p><div class="example-contents"><div class="para">
This example shows the front-matter and a couple of chapters. Lines that start with <code class="literal">#</code> are comments.
</div><pre class="screen">
# Mandatory front-matter
Title = PressGang CCMS Handbook
Subtitle = Guidelines for Writers, Information Architects, Translators, and other Users
Abstract = This guide represents the workflows and methods which generate the best results for CCMS-generated documentation, and should be used as the first point of guidance for using PressGang CCMS
Product = PressGang CCMS
Version = 2.0
Edition = 1
DTD = Docbook 4.5
Copyright Holder = Red Hat, Inc.
# The commented fields below are optional
publican.cfg = [xml_lang: "en-US"
# Change "Book" to "Article" if desired.
# An article can only have sections, not chapters.
type: Book
# You can specify any Publican brand here.
# It needs to be installed in DocBuilder before
# you can use it for PressGang CCMS continuous integration books.
brand: common
chunk_first: 0
# git_branch: docs-rhel-6
# You can specify conditional statement matching here
condition: standard
formats: html,html-single,pdf]
# Debug = [0|1|2]
# Set these variables to populate the feedback link in the Feedback.xml
# BZPRODUCT =
# BZCOMPONENT =
# BZVERSION =
# BZKEYWORDS =
# Uncomment and set this to disable
# automatic assignment of bugs to the
# topic's assigned author
# BZ ASSIGNEE = OFF
[Writer = mstanley]
Chapter: Introduction
About This Guide [N, Concept]
About PressGang CCMS [1234]
Known Issues and Limitations [N, Reference, Writer=misty]
Chapter: Topic-Based Authoring in the CCMS [3797]
About Topic-Based Authoring [N, Concept]
Section: Topic Types
Content [N, Concept]
Task [N, Concept]
Reference [N, Concept]
CSProcessor Map [N, Concept]
Section: Metadata
Per-Topic Metadata [N, Concept]
Per-Map Metadata [N, Concept]
</pre></div></div><br class="example-break" /><div class="formalpara"><div class="title">Structural Elements</div>
The following table lists structural elements of content specification maps, which can be separated from actual topics.
</div><div class="table"><a id="idp7655152"></a><p class="title"><strong>Table 2.2. Structural Elements of Content Maps</strong></p><div class="table-contents"><table summary="Structural Elements of Content Maps"><colgroup><col width="33%" /><col width="33%" /><col width="33%" /></colgroup><thead><tr><th class="" align="left">
Element
</th><th class="" align="left">
Requires corresponding topic?
</th><th class="" align="left">
Description
</th></tr></thead><tbody><tr><td class="" align="left">
Part:
</td><td class="" align="left">
No
</td><td class="" align="left">
<div class="para">
Adds a <part>, which is a Docbook element which holds multiple one or more <chapter> elements.
</div>
. This element cannot be used in Articles.
</td></tr><tr><td class="" align="left">
Chapter:
</td><td class="" align="left">
No
</td><td class="" align="left">
<div class="para">
Adds a <chapter>, which can hold multiple <section> elements, and can optionally be nested below a <part> element. This element cannot be used in Articles.
</div>
</td></tr><tr><td class="" align="left">
Section:
</td><td class="" align="left">
No
</td><td class="" align="left">
<div class="para">
Adds a <section>, which can be nested within another <section>, a <chapter>, or an <article>.
</div>
</td></tr><tr><td class="" align="left">
Preface:
</td><td class="" align="left">
No
</td><td class="" align="left">
<div class="para">
Adds a <preface> element, which can be nested within a <part> or can be a top-level element alongside other top-level elements, such as <chapter> and <appendix>. This element cannot be used in Articles.
</div>
</td></tr><tr><td class="" align="left">
Appendix:
</td><td class="" align="left">
No
</td><td class="" align="left">
<div class="para">
Inserts a <appendix> element, generally near the end of the book, but technically can appear anywhere. This is a top-level element like <chapter>. This element cannot be used in Articles.
</div>
</td></tr><tr><td class="" align="left">
Revision History:
</td><td class="" align="left">
Yes
</td><td class="" align="left">
<div class="para">
Specifies a topic to be used as the container for the <revhistory> entries for a book.
</div>
</td></tr><tr><td class="" align="left">
Feedback:
</td><td class="" align="left">
Yes
</td><td class="" align="left">
<div class="para">
Specifies a topic to be used in place of the stock <code class="filename">Feedback.xml</code> provided by the Publican brand. This element cannot be used in Articles.
</div>
</td></tr><tr><td class="" align="left">
Legal Notice:
</td><td class="" align="left">
Yes
</td><td class="" align="left">
<div class="para">
Specifies a topic to be used in place of the stock <code class="filename">Legal_Notice.xml</code> file provided by the Publican brand. Do not change the <code class="filename">Legal_Notice.xml</code> for Red Hat books without explicit permission from Red Hat Legal and Product Management.
</div>
</td></tr></tbody></table></div></div><br class="table-break" /><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
If a line contains one of the above-mentioned elements and a number in square brackets, the number refers to a topic whose text (but not the title) will be included as the first part of the element's text, before any child topics are included. Some elements, such as <code class="literal">Revision History:</code>, <code class="literal">Feedback:</code>, and <code class="literal">Legal Notice:</code> require a topic to be specified.
</div></div></div><div class="formalpara"><div class="title">Individual Topics</div>
Lines that include only a topic title and square brackets are individual topics. The information between the brackets is metadata. For instance, <code class="literal">[N, Concept]</code> denotes that this is a new topic and is a concept. After the content specification is processed by the CCMS the first time, all topics with <code class="literal">[N]</code> will be added as new topics, and the CSProcessor map will then include the topic ID instead. Topics with only numbers inside the brackets are topics which already exist. As you can see, other metadata, such as the writer or a reference URL can be added.
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=14047" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+14047-473161+%5BLatest%5D&cf_build_id=14047-473161+02+Jul+2013+12%3A54+en-US+%5BLatest%5D&comment=Title%3A+CSProcessor+Map%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="sect-Metadata"></a>2.3. Metadata</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Per-Topic_Metadata"></a>2.3.1. Per-Topic Metadata</h3></div></div></div><div class="para">
Depending on how you look at it, some types of metadata can be stored and tracked without using a CCMS at all. This includes the revision history which is stored in a version-control system and the information which can be gleaned from the specific Docbook markup that is used to tag a document.
</div><div class="para">
If you look specifically at Docbook tagging as metadata, Red Hat has been storing metadata about content for a long time. However, the CCMS lets you go beyond that, and also lets you do more with the metadata itself. Here are a few types of metadata which are tracked by PressGang CCMS and how they can be used. More types of metadata may be added later, and some types which are not considered useful may be removed.
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
Revision info, such as the time, date, writer, and the diff itself
</div></li><li class="listitem"><div class="para">
Products and versions to which a topic has relevance
</div></li><li class="listitem"><div class="para">
Content specifications which use the topic
</div></li><li class="listitem"><div class="para">
Bugs filed against the topic
</div></li><li class="listitem"><div class="para">
Documentation lifecycle information about a topic, such as expiry or deprecation
</div></li><li class="listitem"><div class="para">
Status of peer review or QE review on a topic
</div></li><li class="listitem"><div class="para">
Relevant audiences for a topic
</div></li><li class="listitem"><div class="para">
Keywords and other types of metadata which may be used by search engines or other external consumers
</div></li></ul></div><div class="para">
Some of the ways this metadata can be used include detailed reporting, gap analysis, remixing of content, and documentation lifecycle automation.
</div><div class="para">
Currently, most of this metadata is managed by means of tags, which are checked or unchecked in the UI. The metadata we want and need to capture is under review currently, and may change. The goal is to make the metadata as easy to use as possible, with the least amount of trouble to keep it up to date.
</div><div class="formalpara"><div class="title">New Metadata System</div>
A new metadata system, which was agreed upon by consensus of CCMS users, is not yet implemented. The purpose of the new system is to minimize the amount of metadata that needs to be managed by hand, and to increase the automation of the process. For now, much of the work that will be automated needs to be done by hand. Process can be tracked at <a href="https://bugzilla.redhat.com/show_bug.cgi?id=958331" target="_top">https://bugzilla.redhat.com/show_bug.cgi?id=958331</a>.
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=13983" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+13983-457467+%5BLatest%5D&cf_build_id=13983-457467+05+Jun+2013+15%3A27+en-US+%5BLatest%5D&comment=Title%3A+Per-Topic+Metadata%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Per-Map_Metadata"></a>2.3.2. Per-Map Metadata</h3></div></div></div><div class="para">
Per-map metadata falls into two different categories: metadata which should be applied to each topic automatically, and metadata that only makes sense when looking at a map as a whole document. The former consists of a way for the CSProcessor to consider certain tags as relevant to each topic, and will be covered in detail in the document design section. The latter includes information which only makes sense as a 1:1 relationship with the content itself.
</div><div class="para">
Some of the metadata that applies to a CSProcessor map as a whole includes:
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
Frontmatter and backmatter
</div></li><li class="listitem"><div class="para">
Information needed to build up Bugzilla links for the content
</div></li><li class="listitem"><div class="para">
Revision history
</div></li><li class="listitem"><div class="para">
Audience
</div></li></ul></div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=13994" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+13994-457478+%5BLatest%5D&cf_build_id=13994-457478+05+Jun+2013+15%3A27+en-US+%5BLatest%5D&comment=Title%3A+Per-Map+Metadata%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a id="chap-Planning_and_Designing_Documents"></a>Chapter 3. Planning and Designing Documents</h1></div></div></div><div class="toc"><dl><dt><span class="section"><a href="#About_Topic-Based_Authoring1-1">3.1. About Topic-Based Authoring</a></span></dt><dt><span class="section"><a href="#About_Content_Specifications">3.2. About Content Specifications</a></span></dt><dt><span class="section"><a href="#About_CSProcessor">3.3. About CSProcessor</a></span></dt><dt><span class="section"><a href="#sect-Using_the_CSProcessor">3.4. Using the CSProcessor</a></span></dt><dd><dl><dt><span class="section"><a href="#Install_CSProcessor">3.4.1. Install CSProcessor</a></span></dt><dt><span class="section"><a href="#Use_the_csprocessor_Command">3.4.2. Use the <code class="code">csprocessor</code> Command</a></span></dt><dt><span class="section"><a href="#sect-CSProcessor_Map_Syntax">3.4.3. CSProcessor Map Syntax</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Designing_Documents">3.5. Designing Documents</a></span></dt><dd><dl><dt><span class="section"><a href="#Create_a_Map">3.5.1. Create a Map</a></span></dt><dt><span class="section"><a href="#Modify_a_Map">3.5.2. Modify a Map</a></span></dt><dt><span class="section"><a href="#Freeze_a_Map">3.5.3. Freeze a Map</a></span></dt><dt><span class="section"><a href="#Clone_a_Map">3.5.4. Clone a Map</a></span></dt><dt><span class="section"><a href="#Build_a_Book_from_a_Map">3.5.5. Build a Book from a Map</a></span></dt><dt><span class="section"><a href="#Request_a_Continuous_Integration_Book">3.5.6. Request a Continuous Integration Book</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-CSProcessor_Map_Workflow">3.6. CSProcessor Map Workflow</a></span></dt><dd><dl><dt><span class="section"><a href="#About_the_Workflow_Phases">3.6.1. About the Workflow Phases</a></span></dt><dt><span class="section"><a href="#Move_the_Map_to_the_Next_Phase">3.6.2. Move the Map to the Next Phase</a></span></dt></dl></dd><dt><span class="section"><a href="#sect-Version_Control_in_the_CCMS">3.7. Version Control in the CCMS</a></span></dt><dd><dl><dt><span class="section"><a href="#Topic_Revisions">3.7.1. Topic Revisions</a></span></dt><dt><span class="section"><a href="#Revision-less_Trunk_CSProcessor_Maps">3.7.2. Revision-less (Trunk) and Frozen CSProcessor Maps</a></span></dt><dt><span class="section"><a href="#Modify_a_Topics_Revision_in_a_Frozen_Map">3.7.3. Modify a Topic's Revision in a Frozen Map</a></span></dt><dt><span class="section"><a href="#Compare_Revisions_of_a_Topic">3.7.4. Compare Revisions of a Topic</a></span></dt></dl></dd></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="About_Topic-Based_Authoring1-1"></a>3.1. About Topic-Based Authoring</h2></div></div></div><div class="para">
<em class="firstterm">Topic-based authoring</em> is a methodology for distilling content into <em class="firstterm">topics</em>, which can stand somewhat on their own, and then building a document out of these topics. Topic-based authoring is different from <em class="firstterm">narrative authoring</em>, which assumes that a book or article will be read cover-to-cover.
</div><div class="para">
<em class="firstterm">Darwin Information Typing Architecture (DITA)</em> is the most well-known paradigm for topic-based authoring. Red Hat has borrowed some of the principles of DITA while retaining the Docbook DTD, which provides for a more mature toolchain and richer markup language.
</div><div class="formalpara"><div class="title">Relationship between PressGang CCMS and Topic-Based Authoring</div>
PressGang CCMS does not force a topic-based approach, and a topic-based approach can be used outside the scope of PressGang CCMS. However, the CCMS was designed with a topic-based approach in mind, and works well with this approach.
</div><div class="table"><a id="idp7340336"></a><p class="title"><strong>Table 3.1. Topic-Based vs Narrative Writing</strong></p><div class="table-contents"><table summary="Topic-Based vs Narrative Writing"><colgroup><col width="50%" /><col width="50%" /></colgroup><thead><tr><th class="">
Topic-Based
</th><th class="">
Narrative
</th></tr></thead><tbody><tr><td class="">
<div class="para">
Assumes readers may enter the document at any point
</div>
</td><td class="">
<div class="para">
Assumes readers will start at the beginning and work their way through the book or article
</div>
</td></tr><tr><td class="">
<div class="para">
Allows for repetition of key content at the places in the document where they are needed, without increasing document maintenance
</div>
</td><td class="">
<div class="para">
Uses copy-and-paste or cross-linking for content that is relevant in different areas of the same content
</div>
</td></tr><tr><td class="">
<div class="para">
Allows existing content to be "remixed" into different formats depending on the audience or other factors
</div>
</td><td class="">
<div class="para">
Restructuring of a document requires a lot of work
</div>
</td></tr><tr><td class="">
<div class="para">
Provides for different topic types which have different structures and rules (concept, task, and reference)
</div>
</td><td class="">
<div class="para">
Treats all content the same, because it's basically all words, right?
</div>
</td></tr><tr><td class="">
<div class="para">
Makes it easy for multiple people (and teams) to share and work on common content together, because each "work unit" is small and relatively self-contained
</div>
</td><td class="">
<div class="para">
Typically, one person will own one chapter or one book, because this makes for minimal editing conflicts. This makes it harder to share and review work.
</div>
</td></tr><tr><td class="">
<div class="para">
Because units of documentation are smaller, bugs can be filed right where the problems are.
</div>
</td><td class="">
<div class="para">
Bugs are filed on a per-book basis, with only the bug-filer's description to guide the writer about where to find and fix the problem.
</div>
</td></tr></tbody></table></div></div><br class="table-break" /><div class="para">
These are only a few of the benefits of topic-based authoring. For more information, refer to <a href="http://en.wikipedia.org/wiki/Topic-based_authoring" target="_top">http://en.wikipedia.org/wiki/Topic-based_authoring</a>.
</div><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
It is easy to lose sight of the reader, in the zeal for the topic-based approach. The idea of attempting to categorize content into topic types does not work equally well for all kinds of content, and the judgment of the writer, when thinking about the reader, is the ultimate guide. Sometimes a task needs to have some information in it that looks conceptual, and sometimes a concept needs to have more information than a simple dictionary definition. A task may not always look like a procedure, but sometimes it may look like an illustrated example or a workflow. When categorizing topics, use your judgment. When segmenting content into topics, think about the unit of granularity that makes the most sense for reuse, not the smallest granularity possible.
</div></div></div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=14023" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+14023-457502+%5BLatest%5D&cf_build_id=14023-457502+05+Jun+2013+15%3A28+en-US+%5BLatest%5D&comment=Title%3A+About+Topic-Based+Authoring%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="About_Content_Specifications"></a>3.2. About Content Specifications</h2></div></div></div><div class="para">
A <em class="firstterm">content specification</em> refers to the output of the second stage of documentation according to the planning model espoused by Joanne Hackos. The first stage results in an <em class="firstterm">information plan</em>, which is a list of resources and information available. The content specification is a detailed description of a documentation deliverable. Although it may take different forms, in terms of PressGang CCMS, a content specification is a table of contents of a book or article. Its format is both human-and-machine-readable, and the CCMS can process it to add or update topics and metadata. The content specification is also used to build the payload which will be built by Publican and published.
</div><div class="para">
Currently, the content specification is a text file which is parsed by a command-line client called the <code class="code">csprocessor</code> and stored as a topic in the CCMS. In the near future, the content specification will be stored as a database object, and will be able to be manipulated by a GUI tool which will be part of the web-based UI.
</div><div class="para">
Keeping content specifications separate from the topics they incorporate provides a level of abstraction which allows content to be reused (even within the same book) and remixed with minimal maintenance. For instance, a set of security-related topics in different guides can easily be remixed into a stand-alone Security Guide. When a topic is revised, each guide which uses it can be refreshed to use the new content just by a rebuild, with no extra editing required.
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=14006" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+14006-457489+%5BLatest%5D&cf_build_id=14006-457489+05+Jun+2013+15%3A28+en-US+%5BLatest%5D&comment=Title%3A+About+Content+Specifications%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="About_CSProcessor"></a>3.3. About CSProcessor</h2></div></div></div><div class="para">
The <code class="code">csprocessor</code> is a command-line tool which can be used in RHEL and Fedora to manage content specifications and build books from content based in PressGang CCMS. It is available internally and can be installed using a YUM repository. It communicates with the PressGang CCMS server-side components using the REST API.
</div><div class="note"><div class="admonition_header"><p><strong>Note</strong></p></div><div class="admonition"><div class="para">
At some time in the near future, the CSProcessor command-line utility will be superseded or at least augmented by a web-based interface in the PressGang CCMS UI. This change will coincide with a change in the structure and format of the CSProcessor maps themselves.
</div></div></div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="http://skynet.usersys.redhat.com:8080/pressgang-ccms-ui/#SearchResultsAndTopicView;query;topicIds=14004" target="_top">Edit this topic</a>
</div><div class="RoleCreateBugPara RoleCreateBugPara">
<a href="https://bugzilla.redhat.com/enter_bug.cgi?cf_environment=Build%3A+CSProcessor+Builder+Version+1.12%0ABuild+Name%3A+13968%2C+PressGang+CCMS+Handbook-2.0-1%0ABuild+Date%3A+23-07-2013+13%3A25%3A13%0ATopic+ID%3A+14004-457488+%5BLatest%5D&cf_build_id=14004-457488+05+Jun+2013+15%3A27+en-US+%5BLatest%5D&comment=Title%3A+About+CSProcessor%0A%0ADescribe+the+issue%3A%0A%0A%0ASuggestions+for+improvement%3A%0A%0A%0AAdditional+information%3A&assigned_to=misty%40redhat.com&product=PressGang+CCMS&component=Documentation&version=2.0" target="_top">Report a bug</a>
</div></div><div class="section"><div class="titlepage"><div><div><h2 class="title"><a id="sect-Using_the_CSProcessor"></a>3.4. Using the CSProcessor</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="Install_CSProcessor"></a>3.4.1. Install CSProcessor</h3></div></div></div><div class="itemizedlist"><p class="title"><strong>Prerequisites</strong></p><ul><li class="listitem"><div class="para">
You must be running RHEL or Fedora
</div></li><li class="listitem"><div class="para">
You must be on the internal network or VPN to be able to access the test and production CCMS instances
</div></li><li class="listitem"><div class="para">
You need <code class="code">root</code> or <code class="code">sudo</code> access on your system. These examples assume that you use <code class="code">sudo</code>. If you prefer to gain superuser access another way, remove the <code class="code">sudo</code> from the commands and modify them to suit you.
</div></li></ul></div><div class="procedure"><a id="idp7228480"></a><p class="title"><strong>Procedure 3.1. Task</strong></p><ol class="1"><li class="step"><div class="para">
Open a command terminal.
</div></li><li class="step"><p class="title"><strong>Install the repository.</strong></p><div class="para">
Run one of the following commands to install the repository.
</div><ul class="stepalternatives">
<li class="step"><div class="para">
<code class="code">sudo yum localinstall http://csprocessor.cloud.lab.eng.bne.redhat.com/yum/csp-repo-1-1.noarch.rpm</code>
</div></li>
<li class="step"><div class="para">
<code class="code">sudo rpm -Uvh http://csprocessor.cloud.lab.eng.bne.redhat.com/yum/csp-repo-1-1.noarch.rpm</code>
</div></li>
</ul></li><li class="step"><p class="title"><strong>Install the <code class="code">csprocessor</code> application.</strong></p><div class="para">
Run the following command to install the application.
</div><div class="para">
<code class="code">sudo yum install cspclient</code>
</div></li><li class="step"><p class="title"><strong>Verify that the application is installed.</strong></p><div class="para">