Bug 837960

Talked to Matt about this and here's his reply:

--------------------------------------------------------------------------------
Option 3 would be the best option. One of the design principals we are striving for in the next version of Skynet is to remove an conceptual difference between the tools (be it UI or data structures like CSP Maps) and the final output. 

Both option 1 and 2 require the use to jump around the map looking for relationships, and then conceptually combine those pieces of information to picture what they would look like in the final output. It sounds trivial, but I have found any abstraction between what is presented in the dev phase and what is produced at the end causes problems, especially for new users. Option 3 might bulk out the map with relationships, but listing the relationships right there alongside the topic makes is much less ambiguous, and reflects how the links would be presented in the final output.
--------------------------------------------------------------------------------

Talked to the RHEV team and changed the syntax slightly to show grouping and continuation of data. The new format is:

Option 3:
=========
   Section: Domain Management Tool
     What is the Domain Management Tool? [8673]
     Syntax for the Domain Management Tool [7865]
     Using the Domain Management Tool [7866] 
     [Refers-to:
         Adding Domains to Configuration [8405],
         Edit Domain in Configuration [8406],
         Deleting Domains from Configuration [8407],
         Validating Configuration [8408]]

Added the main functionality into 0.25.0.

I've added long name processing for the three relationship type. R = Refers-to, P = Prerequisite and L = Link-List. (See Bug #836081 for more info on Link-List)

Note: There is currently no validation done on the Topic Title and is essentially just any text to make it human readable. However validation will be added in a future release.

This doesn't seem to work for me, based on c#2 I tried with the following:

        Red Hat Enterprise Virtualization Host Hardware Requirements Overview [7842]$
        [Refers-to:$
          CPU Requirements [7843],$
          RAM Requirements [7844],$
          Storage Requirements [7845],$
          PCI Device Requirements [7846]]$  

When doing csprocessor push I get:

CSProcessor client version: 0.25.1
Loading configuration from /home/sgordon/.config/csprocessor.ini
Loading project configuration from csprocessor.cfg
Connecting to Skynet server: http://skynet.usersys.redhat.com:8080/TopicIndex/

Starting to parse...
Attempting to download all the latest topics...
Starting to validate...
ERROR: Line 38: Duplicated bracket types found.
       -> Red Hat Enterprise Virtualization Host Hardware Requirements Overview [7842]
        [Refers-to:
          CPU Requirements [7843],
ERROR: The Content Specification is not valid.

Oops my fault sorry. I changed the "Refers-to" to "Related-to" since that was it's original meaning mean we first implemented the relationships. If this is an issue then let me know and I'll change it to "Refers-to".

Still seem to have some issues with this, my content spec now reads:

      Section: Red Hat Enterprise Virtualization Host Hardware Requirements$
        Red Hat Enterprise Virtualization Host Hardware Requirements Overview [7842]
        [Related-to:
          Red Hat Enterprise Virtualization Host CPU Requirements [7843],
          Red Hat Enterprise Virtualization Host RAM Requirements [7844],                                                                          
          Red Hat Enterprise Virtualization Host Storage Requirements [7845],
          Red Hat Enterprise Virtualization Host PCI Device Requirements [7846]]
        Red Hat Enterprise Virtualization Host CPU Requirements [7843]
        Red Hat Enterprise Virtualization Host RAM Requirements [7844]
        Red Hat Enterprise Virtualization Host Storage Requirements [7845]
        Red Hat Enterprise Virtualization Host PCI Device Requirements [7846]

In the output I get only the link for the first and last entry listed:

    Section 2.1.3.2, “Red Hat Enterprise Virtualization Host CPU Requirements”
    Section 2.1.3.5, “Red Hat Enterprise Virtualization Host PCI Device Requirements” 

I get the same behaviour when I use Link-List instead of Related-to, there are no errors in the compiler output.

I'll take a look today using your example and find the issue as I had tested with up to 3 links and they all showed.

Verified the error and fixed for 0.25.2.

Cause:

In some situations the lines in the middle of the relationship wasn't getting getting saved during parsing. This was due to a recursion call on the same method and parsing the wrong variable.

Consequence:

Only the first and last relationship were being displayed in the output.

Fix:

Ensure that the line isn't lost and the correct variables are passed.

(In reply to comment #5)
> Oops my fault sorry. I changed the "Refers-to" to "Related-to" since that
> was it's original meaning mean we first implemented the relationships. If
> this is an issue then let me know and I'll change it to "Refers-to".

Maybe it should be "Refer-to"...

"Related-to" is generic (prerequisites are "related-to" as well), and the directionality is unclear ("related-to" works both way). 

"refer-to" or "refers-to" makes the nature and direction of the relationship explicit.

Just checked, everything has been documented as "refer-to":
http://deathstar1.usersys.redhat.com:8080/TopicIndex/Books/Content_Spec_Processor_Guide/index.html#sect-Prerequisites_and_Refer-to_Relationships

Okay, I'll add the "Refer-to" check to the validator so that you can use either. I won't remove the "Related-to" just yet but down the track it is likely to disappear.

From aburden:

The following is producing an "Incorrect attribute format." error when it should be valid syntax:

Installing a Guest Operating System onto a Virtual Machine [7479]
[Prerequisite:
  Creating a new virtual machine from a blank template [7476],
  Explanation of settings in the Virtual Machine Network Interface window [9476]
  Explanation of settings in the New Virtual Machine Disk and Edit Virtual Machine Disk windows [9415]]
[Related-to:
  Virtual Machine Run Once Settings Explained [10821]]

Fixed the latest issue reported by Andrew and will be released as part of 0.26.5.

Cause:

The parser wasn't checking the next line for relationships when the previous relationship (the prerequisites in this case) had more than one relationship.

Consequence:

The parser would think that the "Related-to" relationship was actually a new topic and as such would throw the invalid syntax error.

Fix:

Update the parser to pull in the next line if it ends with a separator this will ensure that when the syntax is valid (not missing the separator) it will process the "Related-to" relationship.

However if the syntax isn't valid then an error will be thrown but the "Related-to" relationship would still be parsed as a topic and throw the invalid attribute message. So also add checks to the set parser to check the next line once it believes to have finished finding all sets to see if the next line looks like a continuation to the current list of sets (ie another relationship or target).

Closing and setting as current release as no QA was performed by the original reporter. If there is still an issue with this bug still than please re-open it.