Formatting issues with the OASIS-styled PDF and HTML files

resource

description

http://tools.oasis-open.org/version-control/browse/wsvn/dita/

DITA TC SVN repository; contains resources used to build official specifications, including the OASIS look-and-feel plugin for PDF generation

num

area

description

notes

status

1

xref

some links dont work

may need help from Robert Anderson

in progress

2

toc and pdd bookmarks

some do not express numbering

should be easy to fix

in progress

3

throughout AH version

fonts should be sans serif

AH configuration issue

in progress

4

Running footer for versos missing; no SpecID (XEP and AH)

5

Running footer for rectos missing # for "page x of #" (AH)

6

Running header missing (XEP, AH)

7

Table text = legible, but might be better if in sans serif font (AH)

8

Level-2 heads have a rule below (XEP, AH)

9

Level-6, Level-7, Level-8, Level-9 heads - could not find instances to review

10

11

12

num

area

description

notes

status

1

Table of Contents

[Hamilton, 30 April 2010] The second line of the toc has no title and a question mark for the page number

[s.park, 13 May 2010] unable to replicate

not a bug

2

heading levels

one of the heading levels is actual small than the next heading level, should be larger by at least 4 pts.

[s.park, 15 May 2010] Modified affected topic title attribute sets and section title attribute sets. New format overview: All topic and section titles numbered, black font, left-margin aligned. Some font size changes implemented for level 3 and 4; headings larger than 4 have the same formatting as 4

done

3

heading levels

[Hamilton, 28 April 2010] In addition to the size of the headings, the 3rd and 4th (assuming we consider the highest level division as "chapters") are indented, which makes them "disappear." If that's OASIS style, then I guess we live with it, but if not, we should consider not indenting those headings.

done

4

heading levels

[Hamilton, 30 April 2010] The OASIS templates use numbered headings, which this PDF does not.

done

5

heading levels

[Hamilton, 30 April 2010] In the Language Reference, I'm surprised that the top level headings ("Base elements, "Technical content elements," etc.) don't start on a new page.

??

6

element: <example>

[Eberlein, 2 February 2010] Body text should not be italicized.

[s.park, 13 May 2010] Easy fix

done

7

element: <shortdesc>

[Eberlein, 2 February 2010] Should be the same size (not smaller) than the body text.

[s.park, 13 May 2010] Easy fix

done

8

lang spec

[Hamilton 5 Feb 2010] In the "Contains" and "Contained by" tables, the left hand column ends up with squashed text. See topic elements ==> topic for examples, but this happens in many places.

[s.park, 13 May 2010] FO processor issue; use AntennaHouse or define wider column

not a bug

9

lang spec

Similar things [to issue #8] happen in other tables, too. For example, it looks like anytime xmlns:ditaarch appears in the Attributes table, the default value column is squashed and unreadable.

[s.park, 13 May 2010] FO processor issue; use AntennaHouse

not a bug

10

linking

[Hamilton, 28 April 2010]Links to list items display strangely. For example, in DITA Markup -> DITA Metadata -> Cascading of Attributes and Metadata. The list under the heading "Rules for cascading in the map" has the following line (Item 8):
"Repeat steps List item. (see page 35) to List item. (see page 35) for each nested map"
The two instances of List item should be replaced with the number of the list item being referenced, instead of being literally "List item." Also, while not as important, the page references don't seem to be that useful for links from one list item to another one inside the same list.

[s.park, 13 May 2010] Content issue

not a bug

11

linking

[Hamilton, 30 April 2010] There is hot text that does not link correctly in the pdf (but does link correctly in the chm).
For example,
Pages 13-14, Basic concepts, All of the headings below this heading are hot, but go nowhere.

Page 18, Navigational independence, the link to keyref at the end of the second paragraph is hot, but goes nowhere.

Page 44 has both working and non-working links, "Key-based (indirect) addressing" does not work, but "The scope attribute" and "reltable" do.

This might be related to the title of the target being "Key-based addressing" rather than "Key-based (indirect) addressing" in the PDF, though it is the latter in the chm.

12

linking

[Hamilton, 30 April 2010] Cross-references are in the form "see heading (see page XX)" The second "see" (in the parenthesized page reference) seems redundant. Also, for some reason the heading is hot, but not the page reference. I'd suggest removing the second "see." I don't think it's essential to make the page number hot, though it would be nice:).

??

13

linking

[Hamilton, 30 April 2010] There are a number of links without page number references. (see page 44, 82, and 86 for a few examples). Can't say this for sure, but it appears that most, if not all of the non-working links do not show a page number, though the inverse is not true (there are links without page numbers that do work). I don't think page number references are needed in the language reference tables, but references that appear in running text, especially ones that say "see title" should have page numbers.

??

14

linking

[Hamilton, 30 April 2010] Link on page 120, "OASIS extensible Name and Address Language (xNAL)" is an external link, but does not display the link itself.

[s.park, 13 May 2010] content issue

not a bug

15

linking

[Hamilton, 30 April 2010] Page 195, In the first note, there is the following link, "<keywords (see page 380)>" Seems like "(see page 380)" should be outside the brackets (<>), assuming you need the link at all; I couldn't find any other links like this.

??

16

paragraph format

[Hamilton, 28 April 2010] There are numerous instances where the second and subsequent paragraphs are indented in the PDF for no apparent reason. This seems to happen throughout the entire document, though the manifestation is sometimes a bit different. Here are a few examples:

Architectural Specification: Base Version, Introduction to DITA:<<BR>><<BR>>Language Reference, Base elements, Topic elements, Basic topic elements: second paragraph

Conformance, very beginning: second and subsequent paragraphs

Appendices, Migrating from DITA 1.1 to 1.2: The second and subsequent paragraphs

Appendices, DITA Mime Type: second and third paragraph

[s.park, 13 May 2010] Easy fix

done

17

footnotes

[Hamilton, 28 April 2010] In the Appendix titled "Element by element recommendations for translators," all of the footnotes appear on the first few pages, even though some of the references are much later. I'd suggest end notes, especially since there are many duplicates (e.g., footnote 2). Making the footnote references hot links would be nice.

[s.park, 13 May 2010] content issue; end notes not supported in DITA, AFIK

not a bug

18

numbering

[Hamilton, 29 April 2010] At least some tables are numbered differently in the PDF than they are in the chm. For example, in the Appendix titled, DITA module and shell implementation reference, Table 4 in the chm (Description of map and its specialization modules) is Table 14 in the pdf.

[s.park, 13 May 2010] This is the effect of different output type definitions

not a bug

19

link formatting

[Hamilton, 30 April 2010] Page 117, link is squashed and illegible.

??

20

element: <note>

[Hamilton, 30 April] Page 1163, The last note on this page is labeled "[other]" This is the only occurrence I could find in the PDF. The label is "Note" in the .chm.

[s.park, 13 May 2010] Sounds like a content (attribute value) issue

??

21

index

[s.park, 13 May 2010] Suppress the index because we're not using it