1) The Topic "Group" says one thing but appears to do something else.
I'm working in Oracle and wanted to document some DDL. Oracle has a concept of Schema which is a subsection of the database.
A table is in a schema and a schema is in a database. I created/modified entries to look like...
Topic Type: Database
Plural: Databases
Index: No
Scope: Start
Class Hierarchy: Yes
Page Title If First: Yes
Keywords:
database, databases
db, dbs
Topic Type: Database Schema
Plural: Database Schemas
Index: No
Keywords:
schema, database schema
Topic Type: Database Table
Plural: Database Tables
Break Lists: Yes
Keywords:
table, tables
database table, database tables
databasetable, databasetables
db table, db tables
dbtable, dbtables
In theory the documentation should come out exactly as if I used Class, Group and Function.
Database topic is modelled on Class
Database Schema topic is modelled on Group
Database Table topic is modelled on Function
I get grouping like:
DB1
-Schema1
-Table1
If I change my comments to actually be Class, Group and Function I get (what I want):
DB1
-Schema1
--Table1
Also for some reason when I use Group instead of Schema documentation appears as if I had used the -nag switch but I didn't.
2) The database is large and will have multiple source code files some having DDL some having PL/SQL Packages and etc. My desire was to put the Database and Database Schema comment at the top of each source file and get combined documentation.
For Example:
File_1.sql contains:
DDL for Database DB1, Schema "Bob", Table1
File_2.sql contains:
DDL for Database DB1, Schema "Bob", Table2 and Schema "Jon", Table3...
I would like the summary to show as
DB1
-Bob
--Table1
--Table2
-Jon
--Table3
Is this possible?
3) It appears that I am forced to organize code like I eventually want the documentation to look.
1) The indentation caused by groups is hard coded to the Group topic right now. Like enums in Topics.txt and Text File and Shebang Script in Languages.txt, a few items have special behaviors that aren't handled by the config files.
Auto-grouping automatically turns off for a class if you specify groups manually. This is documented behavior. However, I may make a command line option that merges them instead of being all or nothing.
2) No, but this is one of the things I'm going to be working on. The original design was very file based, since I wrote it just for my own needs before it became an open source project, and it wasn't an issue then.
3) That's how it works. No rearranging yet.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I have 3 items which I want to discuss.
1) The Topic "Group" says one thing but appears to do something else.
I'm working in Oracle and wanted to document some DDL. Oracle has a concept of Schema which is a subsection of the database.
A table is in a schema and a schema is in a database. I created/modified entries to look like...
Topic Type: Database
Plural: Databases
Index: No
Scope: Start
Class Hierarchy: Yes
Page Title If First: Yes
Keywords:
database, databases
db, dbs
Topic Type: Database Schema
Plural: Database Schemas
Index: No
Keywords:
schema, database schema
Topic Type: Database Table
Plural: Database Tables
Break Lists: Yes
Keywords:
table, tables
database table, database tables
databasetable, databasetables
db table, db tables
dbtable, dbtables
In theory the documentation should come out exactly as if I used Class, Group and Function.
Database topic is modelled on Class
Database Schema topic is modelled on Group
Database Table topic is modelled on Function
I get grouping like:
DB1
-Schema1
-Table1
If I change my comments to actually be Class, Group and Function I get (what I want):
DB1
-Schema1
--Table1
Also for some reason when I use Group instead of Schema documentation appears as if I had used the -nag switch but I didn't.
2) The database is large and will have multiple source code files some having DDL some having PL/SQL Packages and etc. My desire was to put the Database and Database Schema comment at the top of each source file and get combined documentation.
For Example:
File_1.sql contains:
DDL for Database DB1, Schema "Bob", Table1
File_2.sql contains:
DDL for Database DB1, Schema "Bob", Table2 and Schema "Jon", Table3...
I would like the summary to show as
DB1
-Bob
--Table1
--Table2
-Jon
--Table3
Is this possible?
3) It appears that I am forced to organize code like I eventually want the documentation to look.
If in a single source file I have:
// Group: grp1
...
// Variable: Var1
...
// Group: grp2
...
// Variable: Var2
// Variable: Var3
...
// Group: grp1
...
// Function: Func1
...
I get
grp1
-Var1
grp2
-Var2
-Var3
grp1
-Func1
instead of
grp1
-Var1
-Func1
grp2
-Var2
-Var3
Did I do something wrong?
1) The indentation caused by groups is hard coded to the Group topic right now. Like enums in Topics.txt and Text File and Shebang Script in Languages.txt, a few items have special behaviors that aren't handled by the config files.
Auto-grouping automatically turns off for a class if you specify groups manually. This is documented behavior. However, I may make a command line option that merges them instead of being all or nothing.
2) No, but this is one of the things I'm going to be working on. The original design was very file based, since I wrote it just for my own needs before it became an open source project, and it wasn't an issue then.
3) That's how it works. No rearranging yet.
ok...like the product. I'll just add the keywords to class, group and function for now and org my code as much as possible.
And wait for upgrades.
Thanks for everything.
You should only need to do that for groups, since that has the special behavior. Everything else should work fine with your custom topics.