Re: Request to add indentation to the documentation indexes

Hi

On 8/22/19 3:33 AM, Jonathan S. Katz wrote:> On 8/21/19 2:10 AM, Ian Barwick wrote:
 >> Hi
 >>
 >> Would it be possible to tweak the stylesheet to indent the lines in the index
 >> representing the secondary enries?
 >>
 >> To grab a random example, the "alias" entry currently is formatted like
 >> this (*bolded*):
 >>
 >>      *alias*, Table and Column Aliases, Column Labels
 >>      *for table name in query*, Joins Between Tables
 >>      *in the FROM clause*, Table and Column Aliases
 >>      *in the select list*, Column Labels
 >>
 >> which is hard-to-read and makes hard to distinguish the bolded secondary
 >> entries from the actual index entries, and is (for me at leas) a
 >> usability regression
 >> compared to the old website.
 >>
 >> Something like this would be vastly more readable:
 >>
 >>      *alias*, Table and Column Aliases, Column Labels
 >>          *for table name in query*, Joins Between Tables
 >>          *in the FROM clause*, Table and Column Aliases
 >>          *in the select list*, Column Labels
 >>
 >> (which is the format used when building the docs from source with
 >> the default stylesheet).
 >
 > At present, any changes to indentation would need to be done in the XML
 > source. There are pages that already have this, e.g.:
 >
 > https://www.postgresql.org/docs/11/queries-table-expressions.html

What I'm trying to get across is that the index entries are formatted
like this in HTML:

         <dt>alias, Table and Column Aliases, Column Labels</dt>
         <dd>
           <dl>
             <dt>for table name in query, Joins Between Tables</dt>
             <dt>in the FROM clause, Table and Column Aliases</dt>
             <dt>in the select list, Column Labels</dt>
           </dl>
         </dd>

(Note I've stripped this down for clarity).

The <dd> section should be indented for readabilty; browsers usually do this
by default.

However digging about in the style sheets, we have a:

     dd {
       ...
       margin-left:0;
     }

which is unindenting it (evidently originates in a file "_reboot.scss").

See attached screenshots:

   - "pg-docs-index-dd-issue-with-no-indentation.jpg"
     -> the index as-is

   - "pg-docs-index-dd-issue-with-indentation-added.jpg"
     -> here I've dynamically modified the indentation to 2rem, which IMHO
     is a vast improvement.

I suspect the above dd style might be global to the site, so there'd
probably need to be a specific style for the index, e.g.:

     #BOOKINDEX dd {
       margin-left:2rem;
     }

 > Similarly, if we wanted to add emphasis, we'd have to add that to the
 > XML source as well, and then the website can interpret it.
 >
 > There are some options for adding syntax highlighting, though the ones
 > I've seen (and used) involve Javascript, which we've tried to avoid
 > adding on the site except in situations that involve interactivity.
 > However it could be something we consider as long as we have a decent
 > fallback to the current way we display syntax.

I'm not asking for emphasis or syntax highlighting here, my attempt to explain
the issue using only plain text didn't work so well :).


Regards

Ian Barwick


-- 
  Ian Barwick                   https://www.2ndQuadrant.com/
  PostgreSQL Development, 24x7 Support, Training & Services