Changeset 105417 in vbox for trunk/doc

Timestamp:

Jul 19, 2024 11:24:00 AM (10 months ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

164071

Message:

doc/manual: Throw out a lot of meaningless (or outright misleading) content from the ditamap, and do a lot of polishing of the PDF theme. bugref:10705

Location:

trunk/doc/manual

Files:

• en_US/dita/UserManual.ditamap (modified) (3 diffs)
• pdf-theme-UserManual.yaml (modified) (15 diffs)

trunk/doc/manual/en_US/dita/UserManual.ditamap ¶

@@ -2 +2 @@
 <!DOCTYPE bookmap PUBLIC "-//OASIS//DTD DITA BookMap//EN" "bookmap.dtd">
 <!-- The bookmap ID is imperative and matched the Jarvis GUID required to build and pretty much do anything -->
-<bookmap id="EN-VBOX-7-0-USER" xml:lang="en-US">
-   <!--
-         booklibrary renders in bold and is equivalent to title in docbook;
-         mainbooktitle is not in bold and is equivalent to subtitle
-
-         This information gets updated automatically to match the othermeta title value or PDB entry when you run:
-         'DitaUtils.py title -d template.ditamap' or 'DitaUtils.py map-prep -d template.ditamap'
-    -->
+<bookmap id="EN-VBOX-7-1-USER" xml:lang="en-US">
    <booktitle>
-      <booklibrary>Oracle VM VirtualBox</booklibrary>
-      <mainbooktitle>User Manual for Release 7.0</mainbooktitle>
+      <mainbooktitle>Oracle VirtualBox: User Guide for Release 7.1</mainbooktitle>
    </booktitle>
    <bookmeta>
@@ -18 +10 @@
          <published>
             <completed>
-               <month>November</month>
-               <year>2022</year>
+               <month>July</month>
+               <year>2024</year>
             </completed>
          </published>
       </publisherinformation>
 
-      <!--
-         The othermeta title is used as the title for the book in Jarvis and in OHC search.
-         If you don't set this, the value in PDB is used.
-         The booklibrary and mainbooktitle automatically get updated from this title!
-
-         Use a : character to distinguish booklibrary from mainbooktitle
-         To make sure the title is correctly set run:
-         'DitaUtils.py title -d template.ditamap'  or 'DitaUtils.py map-prep -d template.ditamap'
-      -->
-      <othermeta name="title" content="Oracle VM VirtualBox: User Guide for Release 7.0"/>
-
-      <!--
-           Th othermeta pubAlias detemines what the final part of the URL for your book will be (the pubalias in Jarvis).
-           If you don't set it, it will default to the docid in PDB.
-      -->
-         <othermeta name="pubAlias" content="user"/>
-         <othermeta name="jarvis-url" content="https://docs.oracle.com/en/virtualization/virtualbox/7.0/user/"/>
-      <!--
-         For SVN Revision information, you *must* do: `svn propset svn:keywords "Date Author Rev" template.ditamap`
-         on the ditamap when you first add it. You can automatically handle this by editing ~/.subversion/config
-         to add a line entry under [auto-props]:
-         *.ditamap = svn:mime-type=text/xml;svn:keywords=Author Date Id Rev URL;
-      -->
-      <othermeta name="revision" content="$Rev$"/>
-      <othermeta name="rev-date" content="$Date$"/>
-      <othermeta name="ditaval" content="ohc.ditaval"/>
-      <!-- The bookpartno matches the part and revision in PDB  -->
-         <bookid>
-            <bookpartno>F43655-03</bookpartno>
-         </bookid>
-         <bookrights>
-            <copyrfirst>
-               <year>2022</year>
-            </copyrfirst>
-            <bookowner>
-               <organization>Oracle and/or its affiliates. All rights reserved.</organization>
-            </bookowner>
-         </bookrights>
+      <bookrights>
+         <copyrfirst>
+            <year>2022</year>
+         </copyrfirst>
+         <bookowner>
+            <organization>Oracle and/or its affiliates. All rights reserved.</organization>
+         </bookowner>
+      </bookrights>
    </bookmeta>
-   <!--
-    Chunking at chapter level is handled automatically by running:
-    DitaUtils.py chunk -d template.ditamap or 'DitaUtils.py map-prep -d template.ditamap'
-  -->
-    <frontmatter>
+
+   <!-- Chunking should be set with chunk="to-content" in each chapter.  -->
+   <frontmatter>
        <mapref href="conkeyrefs.ditamap" format="ditamap" toc="no" processing-role="resource-only"/>
        <booklists>
@@ -74 +34 @@
           <tablelist/>
        </booklists>
-      <preface href="topics/preface.dita">
+      <preface href="topics/preface.dita" chunk="to-content">
          <topicref href="topics/preface-audience.dita"/>
          <topicref href="topics/preface-reldocs.dita"/>

trunk/doc/manual/pdf-theme-UserManual.yaml ¶

@@ -17 +17 @@
 pdf2:
   font:
-    sans:           'Helvetica, Arial Unicode MS, Tahoma, Batang, SimSun'
-    serif:          'Times New Roman, Times, Arial Unicode MS, Tahoma, Batang, SimSun'
-    monospaced:     'DejaVu Sans Mono, Arial Unicode MS, Consolas, Cascadia Mono'
-    # ^^^ - Important to have proper unicode monospace font so we can use non-breaking hypen (U+2011)
+    sans:           'Noto Sans'
+    serif:          'Noto Serif'
+    monospaced:     'DejaVu Sans Mono'
+    # ^^^ - Important to have proper unicode monospace font so we can use non-breaking hyphen (U+2011)
     #       in syntax diagrams.
+    #
+    # If the PDF contains any use of font "Helvetica" then it might be that the topic nesting is too deep.
+    # Maximum nesting is 4 (not sure what limits it), but all config for h5 is ignored.
 
 page:
@@ -67 +70 @@
     cmdname:
         color:              $brand-color-primary
+        font-family:        $pdf2-font-monospaced
         font-weight:        bold
 
@@ -79 +83 @@
     codeph:
         color:              $brand-color-secondary
+        font-family:        $pdf2-font-monospaced
         font-size:          '0.9 * from-parent(font-size)'
 
@@ -89 +94 @@
     cover-title:
         color:              $brand-color-primary
-        font-size:          36pt
-        font-weight:        bold
-        line-height:        1.5
-        space-before:       195mm
+        font-family:        $pdf2-font-sans
+        font-size:          48pt
+        font-weight:        bold
+        line-height:        1.3
+        space-before:       165mm
 
     example-title:
@@ -100 +106 @@
         caption:
             color:          $brand-color-secondary
+            font-family:    $pdf2-font-sans
             font-size:      9pt
             font-style:     italic
@@ -106 +113 @@
     filepath:
         color:              $brand-color-secondary
+        font-family:        $pdf2-font-monospaced
 
     h1:
         border-after:       solid 2pt $brand-color-inverse
         color:              $brand-color-primary
+        font-family:        $pdf2-font-sans
         font-size:          18pt
+        font-weight:        bold
         space-before:       0pt
         padding-top:        0pt
         space-after:        9pt
-        font-weight:        bold
         title-numbering:    true
 
@@ -120 +129 @@
         border-after:       solid 1pt $brand-color-inverse
         color:              $brand-color-primary
+        font-family:        $pdf2-font-sans
         font-size:          16pt
         font-style:         italic
@@ -128 +138 @@
     h3:
         color:              $brand-color-primary
+        font-family:        $pdf2-font-sans
         font-size:          14pt
         font-weight:        bold
@@ -135 +146 @@
 
     h4:
+        color:              $brand-color-primary
+        font-family:        $pdf2-font-sans
         font-size:          12pt
         font-weight:        bold
@@ -176 +189 @@
     section-title:
         color:              $brand-color-secondary
+        font-family:        $pdf2-font-sans
 
     shortdesc:
         color:              $brand-color-secondary
-        font-size:          13pt
         line-height:        1.3
 
@@ -185 +198 @@
         caption:
             color:          $brand-color-secondary
+            font-family:    $pdf2-font-sans
             font-size:      9pt
             font-style:     italic
@@ -192 +206 @@
         header:
             background-color:   $brand-color-inverse
+            font-family:    $pdf2-font-monospaced       # Hack for arrow glyphs
 
     toc-1:
         color:          $brand-color-primary
         font-family:    $pdf2-font-sans
-        space-before:   5pt
+        space-before:   6pt
         start-indent:   0pt
 
@@ -202 +217 @@
         color:          black
         space-before:   4pt
-        start-indent:   5pt
+        start-indent:   12pt
 
     toc-3:
         color:          black
         space-before:   2pt
-        start-indent:   24pt
+        start-indent:   32pt
 
     toc-4:
         color:          black
         space-before:   2pt
-        start-indent:   40pt
+        start-indent:   48pt
 
     varname:
         color:          $brand-color-secondary
+        font-family:    $pdf2-font-monospaced
         font-style:     italic
 
@@ -224 +240 @@
     #
 
-    # We need to specify the font for each of these elements, so we get a monospace
-    # font capable of doing non-breaking hypen glyps. The default "Courier" does do
-    # that, at least not on Windows.
+    # We need to specify the font for each of these elements, so we get a consistent
+    # monospace font capable of doing non-breaking hyphen glyps. The default "Courier"
+    # does not do the job, at least not on Windows.
     delim:
         font-family:        $pdf2-font-monospaced
@@ -250 +266 @@
     var:
         font-family:        $pdf2-font-monospaced
+    pre:
+        font-family:        $pdf2-font-monospaced
+    userinput:
+        font-family:        $pdf2-font-monospaced
+    screen:
+        font-family:        $pdf2-font-monospaced
+    systemoutput:
+        font-family:        $pdf2-font-monospaced