Known issues in the suse2022-ns styles (as of commit a006259)

[ghost]

@tomschr For you. Don't be scared about the length of this issue. It is not that bad (imo, anyway). The ToC generation issues should be resolved eventually though, as should the missing SBP customization.

• New issues chunked HTML:

  • Optical issue: The left sidebar of articles is usually empty. This looks weird.
    There's a bit of a logical gap here: it was not immediately clear to me what content could be put there, as articles are currently always presented on a single page. It might make some sense to just hide the left column (which is what we do for single-HTML). However, in the case of chunked HTML, that would be inconsistent with all other pages if the article was generated in the context of building. So this item needs some discussion.
    The only items it would be logical to list there are article appendixes. This would need to be fixed in sidetoc.xsl

  • Functional issue: For articles, On this page will list appendixes, even though appendixes are on a different page.
    On this page currently uses the make.lots template. This functionality should probably switch to much simpler custom code.

• New issues single-HTML:

  • Functional issue: books & sets do not have an On this page section.
    This is deliberately disabled. On this page uses make.lots. make.lots currently does not generate book/set sidebars correctly, it only lists appendixes but not parts/chapters. It also generates a List of tables and a List of images into the sidebar (ugly & unwanted).
    This functionality should probably switch to much simpler custom code that is also aware of the difference between chunked and single HTML.

• New issues all HTML:

  • New translation strings in common/l10n/en.xml that are not yet translated:+ <l:gentext key="moredocuments" text="More documents"/>++ <l:gentext key="onthispage" text="On this page"/>++ <l:gentext key="givefeedback" text="Give feedback"/>+ <l:gentext key="reportbug" text="Report an issue"/>+ <l:gentext key="editsource" text="Edit source document"/>++ <l:gentext key="previouspage" text="Previous"/>+ <l:gentext key="nextpage" text="Next"/> ++ ++ + + ++ + " tabindex="0" role="button"> #457

    +   <l:gentext key="moredocuments" text="More documents"/>
    +
    +   <l:gentext key="onthispage" text="On this page"/>
    +
    +   <l:gentext key="givefeedback" text="Give feedback"/>
    +   <l:gentext key="reportbug" text="Report an issue"/>
    +   <l:gentext key="editsource" text="Edit source document"/>
    +
    +   <l:gentext key="previouspage" text="Previous"/>
    +   <l:gentext key="nextpage" text="Next"/>
    

  • The "report an issue" link will only copy the current section/chapter name but not its ordinal number.
    Probably an easy fix, update the code that generates the <section data-id-title="..."> attributes for HTML to use the correct title gentext template (in html.xsl).

• Existing issues that have not been solved:

  • <orgname>SUSE Best Practices</orgname>/--stringparam publishing.series=sbp are not respected.
    Both of these should generate the "series name" onto the PDF title page and above the HTML document title.
    Not sure whether both mechanisms should be kept though: <orgname> is prone to typos (i.e. this will eventually lead to people putting something inconsistent in there), whereas $publishing.series may be a bit restrictive but at least prevents the typos.

  • article/info/cover[@role="logos"] (for SBP/TRD) is not respected.
    This should come out as co-branding logos on the title page of the PDF and below the document title in the HTML.
    Fixed in Create SBP stylesheets structure #507 and Create TRD stylesheets structure  #516

  • In the context of dsc, the breadcrumbs still don't make sense.
    * dsc nav pages have this: SUSE Docs / Supported products / SLES X SPY
    * suse-xsl content pages have this: Overview / SLES Docs / Current guide / Current chapter
    You'll need some way of adding extra breadcrumbs into the suse-xsl-generated docs to fix this.

  • In HTML, the XSLT mode titlepage and associated HTML/SASS/CSS is a mess.
    For SEO reasons, chunked HTML should have an <h1/> on each page, but chapter/part pages usually get an <h2/> or lower.
    The <div class="titlepage"> HTML & CSS are also overcomplicated and messy.
    This code needs a cleanup to remove unhelpful upstream DocBook stylesheet code & code that resulted from toms/my messing-around in 2012/2013.
    Related: Single-HTML articles have very large margins around the article title.

  • PDFs still use Open Sans as the font.

• Things that could be improved:

  • Given the marketing team's insistence on putting a persistent chat bot on the bottom right corner of every page, we may have too much content on the right side now.

  • On this page should highlight the current section in bold (this functionality is called a "scroll-spy").

  • Maybe On this page should list two structural levels rather than a single one.

  • There is a lot of header/footer SASS code that should move over into the docserv-config repo entirely and be delivered with the header/footer HTML directly.
    Related: the footer items for Facebook, Twitter, LinkedIn that are on the www.suse.com are currently not enabled.

  • The documents overview created for sets in the left sidebar is a bit hidden.
    You can click the chevron next to the document title < in the left sidebar to get an overview of all documents of the set.

  • Use HTML 5's <details><summary/>...</details> tags to mark up Q&A content.
    Be aware that the <details/> tag is not particularly compatible with IE 11 and older versions of Edge.

  • The "Applies to" text is currently displayed in the wrong spot if you drag the window wider than 2200px (which nobody ever does).

  • The SUSE header may hide the headline associated with a permalink you opened.
    The older stylesheets did not have this issue, because they had a much more fixed-size header. With the new header that changes between three different heights, depending on the way you scroll, this is nigh-on unfixable. However, lots of other documentation pages have the same issue/worse issues with this. Essentially, the new stylesheets are just following Industry Best Practices.

  • Remove jQuery.
    Modern browsers' JS engines natively include most of the functionality that jQuery was useful for when it was created in ~2005. The JS just needs to be rewritten a bit to accommodate modern browser functionality.