Bug 988633

Summary: Example contains content that should be set elsewhere
Product: [Community] PressGang CCMS Reporter: Lee Newson <lnewson>
Component: DocumentationAssignee: Misty Stanley-Jones <misty>
Status: CLOSED CURRENTRELEASE QA Contact: Lee Newson <lnewson>
Severity: unspecified Docs Contact:
Priority: unspecified    
Version: 2.0CC: lcarlon, lnewson
Target Milestone: ---   
Target Release: ---   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of: Environment:
Build: CSProcessor Builder Version 1.12 Build Name: 13968, PressGang CCMS Handbook-2.0-1 Build Date: 26-07-2013 10:00:23 Topic ID: 14047-481426 [Latest]
Last Closed: 2013-10-09 05:25:13 UTC Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

Description Lee Newson 2013-07-26 02:56:36 UTC
Title: CSProcessor Map

Describe the issue:
The example content spec map contains information in the example publican.cfg that shouldn't be specified. The problematic references are:

xml_lang: en_US
type: book
brand: common

The above three properties are handled elsewhere as other changes generally need to be made, so therefore if they are specified in publican.cfg they will be removed anyways. These are the CSP metadata elements that should be used:

xml_lang -> (none specified at build time and content specs aren't localised)
type -> Type = Book
brand -> Brand = common

Note: Article, Book-Draft and Article-Draft are the other options available for "Type".

Comment 1 Misty Stanley-Jones 2013-07-29 00:31:49 UTC
Can you give me the syntax block to put into the example content spec? I'm not clear on the syntax. It is confusing that we use =, ->, and : all in the content spec.

Comment 2 Lee Newson 2013-07-29 00:46:16 UTC
Basically = is used for key value pairs (metadata mainly), and : is used for array/map based data (grouping of tags, chapters, sections, parts, appendixes, ...). There is one exception to this rule, which is a topics revision value, though in all honesty that is a bug that would require a fair bit of work to fix. (I'm also ignoring the fact that the publican.cfg file uses colons for key value pairs)

So here is what I would consider a correct example (using the current example):

# 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

# 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

publican.cfg = [chunk_first: 0
git_branch: docs-rhel-6
# You can specify conditional statement matching here
# condition: standard]

# 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

# Uncomment these lines and change the XXXX to a valid topic to set
# a custom Revision History, Feedback, or Legal Notice.
# Revision History = [XXXX]
# (or this format, to create a new one, this works for all types)
# Revision History = [N, Revision History]
# Feedback = [XXXX]
# Legal Notice = [XXXX]


[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]

Comment 3 Misty Stanley-Jones 2013-07-29 01:37:33 UTC
Updated in revision 483629.

Comment 4 Lee Newson 2013-07-29 01:40:42 UTC
Looks good thanks Misty :)