| # | 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/publicsite.xsl | |||||
| #1 | 13895 | Paul Allen | Copying using p4convert-docbook | ||
| //guest/perforce_software/doc_build/main/perforce/assets/publicsite/publicsite.xsl | |||||
| #28 | 12854 | eedwards |
Fix JSON table of contents generation: markup in <refentry> tags introduces whitespace that makes the JSON invalid. Now, the TOC entry's title has leading and trailing whitespace trimmed. |
||
| #27 | 12847 | eedwards | Disable Perforce documentation analytics for user builds. | ||
| #26 | 12840 | eedwards |
Upgrade to jQuery 1.11.3 from 1.10.2. There should be no visible or operational changes. |
||
| #25 | 12838 | eedwards |
Fix a bug that broke index generation when UTF-8 entities exist in the index content. |
||
| #24 | 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. |
||
| #23 | 12829 | eedwards |
Follow-on to @1030339: make the reading progress indicator span the entire width of the header. |
||
| #22 | 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. |
||
| #21 | 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. |
||
| #20 | 12825 | eedwards |
Disable the addition of a <br> tag after formal tables/examples/figures etc. for HTML output; it messes with the spacing we control via CSS. |
||
| #19 | 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. |
||
| #18 | 12804 | eedwards |
Add a new processing instruction <?chapterbreak?> which introduces one or two page breaks so that following content appears on a recto page. A corresponding PI has been added to the HTML, which functions as a no-op, to avoid errors during transformation. This will help in the formatting of reference sections, where we prefer the content to appear in its own chapter, but still use recto pagination for each referenced item. |
||
| #17 | 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. |
||
| #16 | 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. |
||
| #15 | 12786 | eedwards |
Additional CSS to improve the experience of printing the HTML documentation. This doesn't address the 'single page' aspect of the job, but individual pages do appear much nicer on paper. |
||
| #14 | 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. |
||
| #13 | 12779 | eedwards |
Follow-on to @871273: Disable inclusion of HighlightJS, and re-enable Google Prettify. |
||
| #12 | 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. |
||
| #11 | 12768 | eedwards |
Update the handling of condition attributes in <para> tags so that it more correctly overrides the official DocBook version. There should be no functional change in current documents, but this should work better if/when para.propagates.style is set. |
||
| #10 | 12767 | eedwards |
Add a processing instruction that allows for page breaks at specific locations in the PDF docs. A similar PI is added for HTML docs, but it is a no-op (since the chunking facility takes care of that) to avoid errors. To use it, add <?pagebreak?> into the XML source where a page break is desired. This will have no effect on existing guides. |
||
| #9 | 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/ |
||
| #8 | 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. |
||
| #7 | 12747 | eedwards |
Add a mechanism to automatically label the top-level items in the sidebar TOC. This is disabled by default, and can be enabled by setting webhelp.autolabel=1 in guides that want it. |
||
| #6 | 12739 | eedwards |
Add XSLT/Javascript to expose the specified language on programlisting tags and pass it on to google-code-prettify. |
||
| #5 | 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. |
||
| #4 | 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. |
||
| #3 | 12732 | eedwards |
HTML + Javascript fix to "focus" the main content container in the new doc HTML presentation so that up/down arrow navigation works without requiring a click on the container container. |
||
| #2 | 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. |
||
| #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/p4-webhelp.xsl | |||||
| #5 | 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 |
||
| #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. |
||