From 5310d8a571cf1f856a9d1dbba36d1efe92a330ec Mon Sep 17 00:00:00 2001 From: Christian Thaeter Date: Thu, 30 Aug 2012 21:53:26 +0200 Subject: [PATCH] RFC: Tags --- doc/devel/rfc/SemanticTags.txt | 146 +++++++++++++++++++++++++ doc/devel/rfc_pending/SemanticTags.txt | 1 + 2 files changed, 147 insertions(+) create mode 100644 doc/devel/rfc/SemanticTags.txt create mode 120000 doc/devel/rfc_pending/SemanticTags.txt diff --git a/doc/devel/rfc/SemanticTags.txt b/doc/devel/rfc/SemanticTags.txt new file mode 100644 index 000000000..363207705 --- /dev/null +++ b/doc/devel/rfc/SemanticTags.txt @@ -0,0 +1,146 @@ +Semantic tags +============= + +// please don't remove the //word: comments + +[grid="all"] +`------------`----------------------- +*State* _Idea_ +*Date* _Do 30 Aug 2012 21:06:54 CEST_ +*Proposed by* Christian Thaeter +------------------------------------- + +******************************************************************************** +.Abstract +We have a lot documentation which needs to be cross referenced. Adding well the +known 'tags' concept and extend it slightly with some semantics will aid future +automatic processing. +******************************************************************************** + +Description +----------- +//description: add a detailed description: + +Every document (including sourcecode) could extended with some metadata, aka tags +which are then used to build automatic crossreferences. + +Commonly tags are just 'words' which are picked up and crossreferenceds. I propose +to extend this scheme slightly. + +Overall this scheme must be very natual and easy to use. A user should not need to +know about the underlying machinery and a tag as in a single lowercase 'word' should +be sufficient in almost all cases. Moreover Tags should be optional. + + +.Ontology + +To give tags some sematics we introduce a simple ontology: + +- Tags can have namespaces, delimited by a dot 'foo.bar.baz'. + Tags are looked up from right to left 'baz' would suffice as long it is unique. + Non unique cases will be handled in context (sometimes non uniqunes is desired) +- We introduce simple "Is a" and "Has a" relationships. These are defined by the + casing of the tag: 'ALL_UPPERCASE' means "Is a" and anything else (including + mixed case) means "Has a". Note that for most cases the "Is a" relation will be + defined implicitly, ín normal cases one doesnt need to care. +- define some tag algebra for lookups (group tags by comma and semicolons, where + comma means 'and' and semicolon means 'or'). Used to query the tag database. + regex/globbing might become handy too. + +.Implicit Tags + +Tags can be implicit by generating them from the document: + +- Derrive tags from the type and location of the Document. + RFC's are 'RFC', source files are 'SOURCE.C' and so on. + +- Derrive Tags from the content of the document. + Asciidoc titles will be used here. A simple preprocessor + generates a tag from a title (make it CamelCase, simplify etc.) + The resulting tag is only used iff it is unique + + +.Use this tags + +Tags are collected/discovered by some script which creates a tag-database +(possibly plaintext asciidoc files) as big project index linking back to the content, +details need to be worked out. + +We create special asciidoc macros for crossreferencing tags for example: 'RFC:foobar' +'SOURCE:builder', details need to be worked out later. + +Note: this Proposal is about including tags in the first place, processing them is only +suggested and left out for later. + + +Tasks +~~~~~ +// List what needs to be done to implement this Proposal: +// * first step ([green]#✔ done#) +// * second step [,yellow]#WIP# + +We need to define how to integrate tags in different documents syntactically. +For RFC's these will likely become a part of the initial table. in other Asciidoc +documents they could be a special comment or header. For Source files special comments +will be used. + +Tags themself will be added lazily on demand (unless we find someone with the patience +to go over all documents and tag them properly). + +Creating the infrastructure handling this tags (cross indexing etc) is not part of +this proposal, nevertheless we planning this since some time and it will be defined in +other RFC's. + + +Discussion +~~~~~~~~~~ + +Pros +^^^^ +// add a fact list/enumeration which make this suitable: +// * foo +// * bar ... + + * Gives a simple graspable way to build a cross reference over the whole project + + +Cons +^^^^ +// fact list of the known/considered bad implications: + + * adding tags and developing the tools manging them will take some time + + +Alternatives +^^^^^^^^^^^^ +//alternatives: explain alternatives and tell why they are not viable: + +We have the ht/dig search function over the Website which give a much simpler way to +find documents. + + +Rationale +--------- +//rationale: Give a concise summary why it should be done *this* way: + +It is very urgent and important that we make our content much easier accessible. + + + +//Conclusion +//---------- +//conclusion: When approbate (this proposal becomes a Final) +// write some conclusions about its process: + + + + +Comments +-------- +//comments: append below + + +//endof_comments: + +'''' +Back to link:/documentation/devel/rfc.html[Lumiera Design Process overview] diff --git a/doc/devel/rfc_pending/SemanticTags.txt b/doc/devel/rfc_pending/SemanticTags.txt new file mode 120000 index 000000000..661e961b3 --- /dev/null +++ b/doc/devel/rfc_pending/SemanticTags.txt @@ -0,0 +1 @@ +../rfc/SemanticTags.txt \ No newline at end of file