[Mono-bugs] [Bug 573334] New: monodoc: Ecma-334 Notational Conventions not followed

[bugzilla_noreply at novell.com]

http://bugzilla.novell.com/show_bug.cgi?id=573334

http://bugzilla.novell.com/show_bug.cgi?id=573334#c0


           Summary: monodoc: Ecma-334 Notational Conventions not followed
    Classification: Mono
           Product: Mono: Doctools
           Version: 2.4.x
          Platform: i686
        OS/Version: Ubuntu
            Status: NEW
          Severity: Normal
          Priority: P5 - None
         Component: Core
        AssignedTo: mario.sopena at gmail.com
        ReportedBy: kevin.cole at gallaudet.edu
         QAContact: mono-bugs at lists.ximian.com
          Found By: Community User
           Blocker: ---


Description of Problem:

Section 5 of the Ecma-334 documentation is correct in the original PDF.
However, in the monodoc package (version 2.4.2.0), it has been changed in a way
that may confuse a beginner.  The documentation in the second paragraph of the
chapter reads:

> Grammar productions include both non-terminal and 
> terminal symbols. In grammar productions, non-terminal
> symbols are shown in italic type, and terminal symbols
> are shown in a fixed-width font. Each non-terminal is
> defined by a set of productions. The first line of a
> set of productions is the name of the non-terminal, 
> followed by a colon. Each successive indented line
> contains the right-hand side for a production that
> has the non-terminal symbol as the left-hand side.
> For example:

The example then shown does NOT use a italics for the non-terminal symbol, it
is NOT followed by a colon, and the terminal symbols are NOT in fixed-width
font. In the original PDF, the example appears as described above.

(As a beginner, unfamiliar with the formal language used "non-terminal and
terminal symbols", I had to download the original PDF document to be certain I
understood the paragraph above. I am guessing the problem continues throughout
the documentation.)

Steps to reproduce the problem:
1. Open document.
2. Read.

Actual Results:

- Document contradicts itself.

Expected Results:

- Document should follow its own conventions.

How often does this happen? 

- Always.

Additional Information:

Either use italics, colons and fixed-with fonts as described, or change the
paragraph to describe the conventions being used in monodoc.  (I suspect the
former to be the more officially approved way of doing things.)

I hope this is the right place to report the bug.  Google searches of monodoc
kept driving me here eventually.

-- 
Configure bugmail: http://bugzilla.novell.com/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are the QA contact for the bug.