Uploaded image for project: 'IMPALA'
  2. IMPALA-3398 Move Impala documentation development to ASF
  3. IMPALA-4643

Consolidate links that point outside the Impala doc bundle



    • Type: Sub-task
    • Status: Resolved
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: Impala 2.7.0
    • Fix Version/s: Impala 2.9.0
    • Component/s: Docs
    • Labels:


      A number of "see also" sorts of references point to related topics in the CDH doc library. This work item is for reorg and simplication to get rid of many <xref> tags that are unused by the standalone Impala docs, and many http:// links pointing to doc pages on cloudera.com.

      We always preserved the ability to get a clean Impala-only doc build be conditionalizing them like so:

      impala_views.xml:        <xref audience="integrated" href="sg_hive_sql.xml#concept_c2q_4qx_p4/col_level_auth_sentry"/><xref audience="standalone" href="https://www.cloudera.com/documentation/enterprise/latest/topics/sg_hive_sql.html" format="html" scope="external"/>

      The Impala-only doc build uses the 'standalone' condition, which means that only the link that resolves to the http:// URL is processed, and the missing sg_hive_sql.xml file doesn't cause a doc build error.

      This work item is to use the DITA <keydef> tag and keyref= attribute for <xref> tags to make these external links easier to genericize. That DITA facility uses a side file similar to a .h where link destinations are centralized. The double <xref> tags with different conditions are condensed down to something like:

      <xref keyref="sentry_hive_syntax"/>

      and the side file can be customized to make the link point to a local .xml file, a remote http:// URL, or even become plain text instead of a link.

      (This mechanism relies on the same <keydef> tag / keyref= attribute that we use for short text substitutions like for the Impala release numbers. That tagging idiom does double duty.)




            • Assignee:
              jrussell John Russell
              jrussell John Russell
            • Votes:
              0 Vote for this issue
              3 Start watching this issue


              • Created: