| # | Change | User | Description | Committed | |
|---|---|---|---|---|---|
| #3 | 26953 | Paul Allen | Move //guest/perforce_software/p4convert to //guest/perforce_software/p4convert/main | ||
| #2 | 14806 | Paul Allen | Update docs and add +w. | ||
| #1 | 13919 | Paul Allen | part 1 of copy | ||
| //guest/paul_allen/p4convert-maven/docs/perforce/assets/publicsite/css/perforce.css | |||||
| #1 | 13895 | Paul Allen | Copying using p4convert-docbook | ||
| //guest/perforce_software/doc_build/main/perforce/assets/publicsite/css/perforce.css | |||||
| #50 | 12837 | eedwards |
#review-1029519 Change the way that the TOC is generated for the HTML presentation: - no longer include the TOC in each generated HTML page. - generate a JSON file representing the TOC. - add javascript to read the TOC in JSON format, and generate the appropriate HTML. - Remove the noscript block that prevents using the documentation with javascript disabled; just hide the search button because you can't use search without javascript. |
||
| #49 | 12831 | eedwards |
Fix a minor vertical alignment problem in the keyboard shortcuts dialog. |
||
| #48 | 12828 | eedwards |
#review-1028126 Update the logo for both PDF, HTML, and CHM output. Includes updated favicon.ico for the HTML output. Includes some additional tweaks: - In the HTML presentation, the "book" icon (to access the PDF, if available) and the magnifying glass icon for searching both look more clickable, using colors from the latest perforce.com design. - Also, both icons stick to the right edge of the doc content, rather than the right edge of the browser. - The background color in the HTML presentation is now plain white; the gradient image is removed. - The Google Analytics code is now included in the HTML presentation by default. Individual guides can disable this by setting the DocBook parameter perforce.analytics=0. Once this change is in place, subsequent generation of guides will incorporate these changes. |
||
| #47 | 12827 | eedwards |
Add an estimate of reading time to the top of each HTML page. Also add an indicator of reading progress to the fixed header. |
||
| #46 | 12822 | eedwards |
Add additonal styles to provide the correct stacking order for popup elements. This should make them more reliably clickable. |
||
| #45 | 12820 | eedwards | CSS fix to improve popup image placement. | ||
| #44 | 12819 | eedwards |
Improve the appearance of numbered lists within admonitions by applying admonition-specific colors to the left border and border/background of the number. |
||
| #43 | 12817 | eedwards | Improve the presentation of indexes in PDF/HTML. | ||
| #42 | 12816 | eedwards |
Adjust the selectors for eliminating paragraph margins to be more specific, to avoid removing the margins for paragraphs following pre blocks. |
||
| #41 | 12810 | eedwards |
Add styling tweaks for images with specified sizes. When this occurs, DocBook creates a table to wrap around the image, and we want to turn off borders, cell padding, and the image's "max-width: 100%" styling to achieve the desired presentation. |
||
| #40 | 12809 | eedwards |
#review-954548 Add the infrastructure to present a "PDF" link in the header bar in the HTML presentation. Not all guides provide PDF versions, so this is configurable on a guide-by-guide basis. The default is to omit the link. When a guide provides a PDF version, set the pdf.available attribute to the name of the PDF file that the link should target. For example, in P4Guide's publicsite build.properties: pdf.available=p4guide.pdf A subsequent changelist will apply this attribute to all of the server guides. |
||
| #39 | 12801 | eedwards | CSS fix for spacing of entries in a <variablelist>. | ||
| #38 | 12800 | eedwards |
Doc presentation tweaks: - For PDF cover page: - move logo to top-left from bottom right - move title down - move subtitle near bottom - add <pubdate> presentation below subtitle (the <subtitle> now specifies the doc version) - tweaked font sizes - For HTML: - Add Perforce logo to header bar. - Add <subtitle> in brackets after guide title. |
||
| #37 | 12795 | eedwards |
#review-932846 Tweak the styling for headings in the HTML presentation: - make second-level and third-level headings slightly larger, to better visually distinguish them from lower-level headings - make second-level headings for preface, appendix, and reference "chapters" consistent with chapters. - better organization of the heading styles to group like styling together, and demonstrate the progression of styling. - remove the border between second-level sections in exchange for greater whitespace between them. - reference sections with partintro blocks included an extra horizontal rule, which is no longer displayed. - Includes a tweak to allow Firefox to scale images in a response manner. |
||
| #36 | 12793 | eedwards |
Tweak the color of the bottom border of a table to match the bottom borders of cells within the table. |
||
| #35 | 12792 | eedwards |
A few updates to presentation for HTML and PDF: - Chapter cross-references no longer appear in italics. - For PDF, <gui*> tag content renders in bold, to match the HTML output. - HTML cross-references to chapters now appears in quotation marks, but cross-references to sections now have the quotation marks removed. - A number of spacing issues in the HTML output between list items, admonitions, images, and a following paragraph have been resolved. |
||
| #34 | 12784 | eedwards |
Improved nav pane scroll position when moving from page to page in a guide. The behaviour isn't perfect in all situations yet, but is notably better. |
||
| #33 | 12783 | eedwards |
Add some margin below "framed" images to provide better separation for following content. |
||
| #32 | 12782 | eedwards |
Tweak CSS so that pop-up images, which only appear in the Swarm docs currently, are positioned properly. Should have no other visible impact. |
||
| #31 | 12780 | eedwards |
Adjust the paragraph spacing within admonitions so that intermediary <literallayout> tags present as expected. |
||
| #30 | 12776 | eedwards |
#review-851775 Updates to the HTML presentation: - remove the double DOCTYPE declarations. - revise markup so that the content is no longer in an immovable container. This should allow the scroll position to be maintained by the browser and work as expected after users navigate within a page and then use the browser's back button. - rename the generated search index file to 'index.js' to avoid a mimetype issue. Also, made the search code tolerant of a missing index.js. - fix scrolling to targeted locations in a guide by applying an offset to the scroll to move the target out from under the header, and to animate the scroll. |
||
| #29 | 12775 | eedwards |
Add HTML formatting for <simplelist> tags. (The PDF formatting is already adequate). This should have no effect on existing docs, as <simplelist> does not appear to be used anywhere. Added to format a 'table' that appears in the forthcoming P4Convert docs (conversion to DocBook). |
||
| #28 | 12773 | eedwards |
Add an additional override to Bootstrap so that code blocks (in <programlisting> tags) do not word wrap when content that could be wrapped is near the right border of the text area in HTML. |
||
| #27 | 12772 | eedwards |
Minor CSS tweak to target pre-formatted only at the end of an admonition. |
||
| #26 | 12771 | eedwards |
Improve the presentation of pre-formatted text in admonitions for the HTML output: - remove the negative left/right margins so that the border around the text doesn't run into the admonition border. - if the pre-formatted text is the last element in an admonition, remove its bottom margin. - adjust the border and background color of the pre-formatted text to better match the color of the different types of admonitions. |
||
| #25 | 12769 | eedwards |
HTML style tweaks: - for Internet Explorer 11, hide the browser's own 'clear' button on input fields to prevent an ugly display problem where IE's clear button overlaps our own button. - make the border around <programlisting> tags just a touch lighter/less constrasty. - make <replaceable> content within <filename> tags inherit the <filename> color. - provide styling to help fix a vertical alignment issue when including "thumb" graphics in a paragraph. Documents that could use this fix need to change the <para> tag to <para condition="thumb">. |
||
| #24 | 12766 | eedwards |
Updates to the HTML presentation for docs to better support users with Internet Explorer 8: - removed used of HTML5 tags, such as header, footer and nav, which IE8 doesn't understand at all. - add Respond.js (MIT license), which simulates CSS media queries in IE8. - fix some issues with the javascript that IE8 could not handle. - add a custom IE8 stylesheet to include some very specific tweaks. The HTML for the following two guides has been updated, and is available for review for a limited time: http://ee.perforce.ca/docs/p4dist.ie8/ http://ee.perforce.ca/docs/swarm/ |
||
| #23 | 12765 | eedwards |
Adjust margin for the heading title so that a guide's title appears centered vertically. |
||
| #22 | 12764 | eedwards |
Make the style which presents the first paragraph in a procedure step bold apply more specifically, so that subordinate list paragraphs do not also become bold. |
||
| #21 | 12762 | eedwards | Fix the color for linked <envar> and <uri> tags. | ||
| #20 | 12759 | eedwards |
Improve specificity of :target styling so that only the TOC element clicked gets highlighted, rather than that element and its enclosed subsections. |
||
| #19 | 12758 | eedwards |
Updates to the HTML doc presentation's search interface: - Add checkbox to toggle whether partial match results will be displayed or not - Replace obscure water droplet icon with checkbox and label to make it obvious that clicking toggles the highlighting of search terms in the current page - Report results by type: phrase matches, exact term matches, and partial matches, using a heading to indicate each group. |
||
| #18 | 12754 | eedwards |
Move the header text up a couple of pixels. Add 2px of top padding to the nav sidebar. Thanks Stew! |
||
| #17 | 12753 | eedwards |
Enable inertia scrolling for the main content, and both the TOC and search sidebars. |
||
| #16 | 12752 | eedwards |
Several doc presentation/interactiontweaks: - on page load, the navigation sidebar is scrolled to show the current section (as well as can be expected) - refactored the keypress handling to use a switch statement. This makes it easier to handle multiple keys with the same logic. - add a modal dialog describing the keyboard shortcuts available while viewing the docs. |
||
| #15 | 12751 | eedwards |
Tweak styles for literallayout such that only the last <br> tag gets hidden. This maintains the expected use of literallayout for multi-line, non-monospaced presentation, but also permits the common practice of injecting a line-break where needed. |
||
| #14 | 12750 | eedwards |
Add in styles for targeted elements, which makes finding where xref links point much easier. |
||
| #13 | 12749 | eedwards |
Adjustments to make the documentation presentation very similar to the public web site. Notable changes: - fix scrollSpy logic that was failing to match section identifiers containing periods - the navigation footer stays in view at all sizes - the background, colours, font sizes, etc. are now identical/similar to the public web site. - we cannot currently use the public web site's fonts due to a licensing issue. |
||
| #12 | 12745 | eedwards |
Remove the "external link" indicator from anchor tags styled as buttons. |
||
| #11 | 12744 | eedwards |
Make guibutton, guilabel, guimenu, guimenuitem, and guisubmenu content appear in bold. |
||
| #10 | 12743 | eedwards |
Make the first paragraph in a procedure step bold for the HTML docs. |
||
| #9 | 12742 | eedwards |
Add javascript from swarm.js to handle thumbnail and popup images, including adding a "Click to expand" indicator for popup images. A subsequent changelist will remove this functionality from the Swarm customizations, as this capability is now available for all guides. |
||
| #8 | 12741 | eedwards |
Adjust CSS to prevent admonitions in orderedlists from overlapping any immediately preceding images. |
||
| #7 | 12740 | eedwards |
Doc presentation style tweaks: - make the header 20% shorter. - make the guide title/version 16% smaller. - hide the left border for nested TOC entries. - lighten the hover colours for the sidebar links. - Use a cursor change to indicate that the term highlight link (the water droplet) is clickable. Also, made the "clear search" button clear the search results. |
||
| #6 | 12738 | eedwards |
Infrastructure updates to support new Swarm DocBook documentation: - Strip out XSLTHL; it does a poor job of highlighting the kinds of syntax included in our documentation, and it does an awful job when code to be highlighted contains other markup, such as xref, link, or replaceable. - Add in google-code-prettify (from Swarm) so that generated HTML has fairly decent syntax highlighting for many of the code examples we use. Further work on syntax highlighting, particularly for PDF output, is required. - Disable TOC generation in HTML; the HTML template already includes the full TOC as a sidebar on every page. - Update the xmlns attribute and image URL filtering. - Fix a bug in HTML page title XSL that often prevented the current section title from being included. This was more obvious in the Swarm documentation which chunks into pages by section, rather than by chapter. - Update the HTML indexer to process multiple HTML files in one pass for performance, and overall simplify the code structure. - Adjust sidebar TOC activation logic to allow Bootstrap's scrollSpy code to work with section-based chunking. - Re-introduce the "brand" markup in the HTML doc heading so that Swarm's documentation can include its logo. Other guides can do so if required, but none have been updated to do so yet. - Add facility for guide-specific custom javacsript inclusion. - Add facility to apply custom CSS classes to images in documentation. This is used in Swarm documentation to provide thumbnail, popup, and "framed" images. - Adjust xref and link text to just report the chapter or section name, without the preamble text, for example: "the section called". - Add <replaceable role="bold"> to provide a second kind of emphasis to programlistings. - Added a subtle color to <filename> content, to help distinguish from other literal text. - Removed the separator rule from the first section heading while chunking by section. - Added Swarm's orderedlist styling so that each numbered item has a circle around the number and a vertical bar indicating the extend of the item. - Added a visual indicator when a link points to an external document. - Rewrote the javascript search code to search for exact and fuzzy terms matches, as well as phrases. Relevance scoring is included, but likely needs some fine tuning to suit our documentation. |
||
| #5 | 12734 | eedwards |
Replace the Java-based HTML indexer with a Python-based one. The Java-based HTML indexer was based on stemming, which can reduce the size of the index notably. However, stemming producespoor search behaviour, and is language specific. For example, the word 'documentation' has a stem of 'document'. When a user searches for 'docu', 'document' is not found. Also, all punctuation was stripped, making searches for IP addresses or depot paths impossible. The Python-based indexer collects all whitespace-separated tokens. The resulting index is around 10% larger than the stemmed index, but permits much more reasonable results, particularly while the user is still typing in search terms. The Python-based indexer should be cross-platform, but has to date only been tested on Mac OSX. It should work as-is on Linux, but further work may be required on Windows or other platforms. Also, there is room for optimization, particularly when a large number of HTML documents are to be indexed. Searching multiple terms is possible, and each HTML page must match all entered terms. There is nothing fancy about handling the search terms, no conjunctions, phrase searching, etc. Depending on user feedback, we may need to add more sophistication in the future. Included in this change: - the Python indexer - removed use of Java-based indexer from common build.xml and applied the Python indexer - added additional image src filtering - better build commentary in certain targets - rewrote the client-side searching - fixed the content of the HTML <title> tags to be '<chapter> // <book>', or just '<book>' when necessary. Search results strip off the ' // <book>' to be concise. - identify results as 'pages' rather than results, as each page may contain multiple matches. - results now indicate how many matches to expect on each page. - re-enabled indexing/search for CmdRef, P4API, P4Dist, and P4Guide. |
||
| #4 | 12733 | eedwards |
Add more xmlns attribute cleanup, and adjust how included images get processed. |
||
| #3 | 12730 | eedwards |
HTML doc presentation tweaks: - turn off the search functionality as it currently has issues making it unreliable. A fix will be applied in a future changelist. - remove the Perforce logo as it is too large and potentially violates several logo style rules. I'll discuss options with our graphics dept. - ensure that code samples can be scrolled horizontally, rather than using word wrapping, if they don't fit in the browser width. |
||
| #2 | 12729 | eedwards |
Implement a few HTML presentation tweaks: - make body content images reduce their size to match the column width as the browser width is reduced. - add a separating line above top-level section headings, to better indicate the section transition. - add more space after tabular information. - remove alternate background color from tabular information; no more zebra striping. |
||
| #1 | 12728 | eedwards |
Upgrade ANT doc build infrastructure to assemble PDFs: - remove non-namespaced DocBook source and add namespaced DocBook source. - add Apache FOP 1.1 - copy fonts, images, XSL into _build, establishing new asset structure. The original structure remains until all guides using it can be upgraded, and several other issues can be resolved. - updated build.xml to allow for per-target build properties. - upgraded the P4SAG to use the new infrastructure. - tweaked admonition presentation in PDFs to remove admonition graphics, and resemble closely the presentation used in the new HTML layout, including the same colors. With these changes, building PDFs involves using a shell, navigating into the guide's directory (just P4SAG for now), and executing "ant pdf". Issues still to be resolved: - PDF generation encounters several warnings about missing fonts (bold versions of Symbol and ZapfDingbats), and a couple of locations where the page content exceeds the defined content area. - Due to issues within Apache FOP, PDF generation emits a substantial amount of output that is not easily suppressed without losing important warning information. - Apache FOP's interface to ANT does not expose a way to set the font base directory. The current configuration does work under Mac OSX, but further testing on Windows will need to be done to determine if the relative paths defined continue to work. The workaround is for Windows users to customize the fop-config.xml to provide absolute system paths to the required fonts. - HTML generation needs further browser testing, and exhibits broken navigation on iOS browsers within the TOC sidebar. - A number of PDF and HTML presentation tweaks still need to be made, for example: sidebars, gui* DocBook tags, whitespace, section separation, etc. |
||
| //guest/perforce_software/doc_build/main/perforce/assets/webhelp/css/perforce.css | |||||
| #6 | 12727 | eedwards |
Further presentation tweaks to the prototype HTML docs: - improve the presentation of the noscript warning when javascript is disabled. - customize the javascript disabled text to refer to 'documentation' instead of 'this site' - remove some stray styles and cruft that interfered with the intended presentation |
||
| #5 | 12726 | eedwards |
Tweaks to the TOC presentation in prototype HTML for docs: - Animated open/close of TOC section - Reflect open/close state in TOC section expansion button - Made section nesting more visually apparent |
||
| #4 | 12725 | eedwards |
Fixes for prototype HTML presentation: - don't attempt to highlight search terms when there are none - adjust inline-block styling in the header so that the text-overflow property takes effect as expected - use smaller font sizes for headings for narrower browsers, and apply transitions to heading font sizes - unroll transition styles to include all browser-specific transition styles. |
||
| #3 | 12724 | eedwards |
Tweak prototype HTML's CSS to prevent a problem where the body content's left margin could be off-screen on initial page load for narrow browsers. |
||
| #2 | 12721 | eedwards |
Tweaks to the prototype HTML presentation for docs: - use CSS classes rather than hard-coded values in javascript to implement sidebar open/close - made the search sidebar disappear when not open, not just to the right where it can be seen in wide browsers - made the TOC sidebar disappear when the search sidebar appears (at narrow browser widths), and vice-versa. |
||
| #1 | 12720 | eedwards |
Apply better organization for DocBook transformation assets. In the future, other output target assets will appear as peers of webhelp, within the assets directory. |
||
| //guest/perforce_software/doc_build/main/perforce/webhelp_assets/css/perforce.css | |||||
| #4 | 12719 | eedwards |
Minor updates to prototype HTML presentation: - make ScrollSpy work, so that the current section of the documentation is highlighted in the sidebar TOC. - add expander buttons to the TOC so that users can manually explore the TOC. - remove the now-unused SIDR code. - remove some cruft. |
||
| #3 | 12718 | eedwards |
WebHelp transformation improvements: - consolidate the Java indexer's output files into a single file to reduce HTTP requests, and tidy up the search assets the indexer created - move the search interface and results into their own pane on the right side of the display - make search incremental as users type - replace existing navigation links with a TOC sidebar that is displayed when the browser is wide enough, or use a footer with prev/next links when the browser is too narrow. In the narrow presentation, the TOC sidebar can be toggled open. - Various improvements to colours, formatting, at various browser sizes. |
||
| #2 | 12717 | eedwards |
Initial prototype of new HTML generation intended to exist on the Perforce public web site. The updates features a more responsive design, removal of frames, styling improvements. More work needs to be done to ensure robust presentation across various devices, and further design tweaks may be required once various stakeholders get a chance to have a look. Future infrastructure work will need to be done: - incorporate PDF generation - some organizational tweaks to make additional output targets easy to add - HTML validation assets need to be added/incorporated |
||
| #1 | 12716 | eedwards |
Initial checkin of infrastructure to process DocBook XML into WebHelp format. The purpose of this change is to lay the groundwork that will allow all published Perforce documentation to be converted to HTML (and eventually PDF and other formats) in a consistent manner, independent of tools, and eventually allow for automated documentation builds. The latest versions of DocBook (1.78.1), Saxon (6.5.5), Xalan-J (2.7.1), and XSLTHL (2.1.0) are included, as well as generic customization capability and per-guide customizations. More work needs to be done to the customization layers to fully support their use from an XML authoring tool, such as oXygen, which will appear in a future change. Note: This change only includes configuration to build WebHelp for the P4SAG. Further work is required before the infrastructure can be applied to other guides. WARNING: For anyone using oXygen to produce WebHelp, there is a known incompatibility: <imagedata> tags in oXygen are verified for file existence, and the HTML is subsequently patched to resolve to the output directory. The non-oXygen WebHelp generation does not include the patch operation, so images are broken. The <imagedata> can be updated to indicate the relative path in the output directory, but then the oXygen transformation will fail. This will be fixed in a future change. |
||