By default, all Oracle identifiers _ARE upper case; the intention was to make the documentation work for the majority of sites, where code is entered ad_hoc, not in mixed case.
Oracle - default upper case, mixed case by enclosing with double quotes(")
EnterpriseDB Postgres Plus - default lower case, mixed case by enclosing with double quotes(")
[
This is because PostgresPlus' Oracle compatibilty is built on top of Postgres, which is by default lower case.
]
There are 2 stages in documentation generation:-
a) code retrieval, parsing and generation of Application.xml;
b) HTML generation using XSLT and Application.xml
The command-line parameters are confusing (down to me); intention was
defaultNamesCase - the underlying database identifier/keyword case (Oracle upper, EnterpriseDB lower), the setting defaulting to uppercase.
namesUpperCase|namesLowerCase|namesDefaultCase - the desired case in the documentation, defaulting to default case (and due to the default value of the default case setting upper case).
This means that currently unquoted identifiers in the generated Application.xml are either upper case or lowercase: quoted identifiers are saved as is (unless namesUpperCase or namesLowerCase are set).
In order to get the intra-documentation hyperlinking working on case-sensitive operating systems (Unix/Linux), I further compromised the command-line settings by hacking the XLST to ensure that the filenames and links were to a common case.
If the code is documented from the database, the object names will be retrieved
as stored in the database, normally in upper case, _AND QUOTED!!. This will happen however the original code was written.
In order to get mixed case output
a) allow mixed case identifiers to be stored in Application.xml;
b) allow the XSLT to generate mixed-case visible documentation;
c) allow the XSLT to generate consistent, working filenames and hyperlinks.
a) requires changes to the command-line processing, the Settings and the purifyIdentifier procedure: this trickles down to the ANT and Maven tasks.
b) and c) may be accomplished by saving the requested settings in the existing GENERATOR section of Application.xml and using them to control how the HTML is generated.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
PLDoc has a new option for the defaultNamesCase command-line flag
"-defaultNamescase mixed" will mean that names are not converted (-namesuppercase -nameslowercase flags will override this)
PLDocTask ANT task has 2 new options for the nameCase property:
mixed (all names are left unconverted)
default (Oracle default - unquoted names are converted to uppercase, quoted names are left mixed case);
PLDoc Maven Plugin 2.10
The plugin has inherited the PLDocTask ANT task's nameCase property, with 4 possible values:-
lower (coerce all names to lower case);
upper (coerce all names to upper case);
mixed (all names are left unconverted)
default (Oracle default - unquoted names are converted to upper case, quoted names are left mixed case);
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
View and moderate all "bugs Discussion" comments posted by this user
Mark all as spam, and block user from posting to "Bugs"
View and moderate all "bugs Discussion" comments posted by this user
Mark all as spam, and block user from posting to "Bugs"
View and moderate all "bugs Discussion" comments posted by this user
Mark all as spam, and block user from posting to "Bugs"
View and moderate all "bugs Discussion" comments posted by this user
Mark all as spam, and block user from posting to "Bugs"
By default, all Oracle identifiers _ARE upper case; the intention was to make the documentation work for the majority of sites, where code is entered ad_hoc, not in mixed case.
Oracle - default upper case, mixed case by enclosing with double quotes(")
EnterpriseDB Postgres Plus - default lower case, mixed case by enclosing with double quotes(")
[
This is because PostgresPlus' Oracle compatibilty is built on top of Postgres, which is by default lower case.
]
There are 2 stages in documentation generation:-
a) code retrieval, parsing and generation of Application.xml;
b) HTML generation using XSLT and Application.xml
The command-line parameters are confusing (down to me); intention was
defaultNamesCase - the underlying database identifier/keyword case (Oracle upper, EnterpriseDB lower), the setting defaulting to uppercase.
namesUpperCase|namesLowerCase|namesDefaultCase - the desired case in the documentation, defaulting to default case (and due to the default value of the default case setting upper case).
This means that currently unquoted identifiers in the generated Application.xml are either upper case or lowercase: quoted identifiers are saved as is (unless namesUpperCase or namesLowerCase are set).
In order to get the intra-documentation hyperlinking working on case-sensitive operating systems (Unix/Linux), I further compromised the command-line settings by hacking the XLST to ensure that the filenames and links were to a common case.
If the code is documented from the database, the object names will be retrieved
as stored in the database, normally in upper case, _AND QUOTED!!. This will happen however the original code was written.
In order to get mixed case output
a) allow mixed case identifiers to be stored in Application.xml;
b) allow the XSLT to generate mixed-case visible documentation;
c) allow the XSLT to generate consistent, working filenames and hyperlinks.
a) requires changes to the command-line processing, the Settings and the purifyIdentifier procedure: this trickles down to the ANT and Maven tasks.
b) and c) may be accomplished by saving the requested settings in the existing GENERATOR section of Application.xml and using them to control how the HTML is generated.
PLDoc Release 1.1.0
PLDoc has a new option for the defaultNamesCase command-line flag
"-defaultNamescase mixed" will mean that names are not converted (-namesuppercase -nameslowercase flags will override this)
PLDocTask ANT task has 2 new options for the nameCase property:
mixed (all names are left unconverted)
default (Oracle default - unquoted names are converted to uppercase, quoted names are left mixed case);
PLDoc Maven Plugin 2.10
The plugin has inherited the PLDocTask ANT task's nameCase property, with 4 possible values:-
lower (coerce all names to lower case);
upper (coerce all names to upper case);
mixed (all names are left unconverted)
default (Oracle default - unquoted names are converted to upper case, quoted names are left mixed case);
Release 1.1.1 corrected the case of the landing page links
Ready for closing