[LLVMbugs] [Bug 1547] NEW: Documentation Requirements

[bugzilla-daemon at cs.uiuc.edu]

http://llvm.org/bugs/show_bug.cgi?id=1547

           Summary: Documentation Requirements
           Product: Website
           Version: unspecified
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Documentation
        AssignedTo: unassignedbugs at nondot.org
        ReportedBy: rspencer at reidspencer.com


With the new website coming online soonish, we need to think about how llvm
modules' documentation will be presented. Right now, everything's in one
directory (llvm/trunk/docs) but with the need to integrate llvm-gcc, hlvm, etc.,
we need a new plan. This PR is for tracking the issues and developing a plan.

Here are some of the requirements:

1. We want to retain a mapping of http://llvm.org/docs to the top level project
   (community) documentation, probably located the website module, or possibly
   the llvm-top module.  This would have the stuff that applies to all modules
   (DeveloperPolicy, License, etc.)

2. Each module should put its module specific documentation into a directory
   named "docs". (i.e. .../trunk/docs). 

3. Each module's documentation should appear under http://llvm.org/docs/{mod}
   where {mod} is the module name. These become the "sections" of the overall
   documentation, one per module.

4. The top level documentation should have a menu of the various modules with
   a link to each.

5. We want to allow users to review the documentation offline as well as online.

6. Auto-generated documentation should be as easy to set up offline as well as
   online.

Some of the issues are:

1. With Chris' planned usage of SSI on the new web site, offline viewing could
   get rather ugly. The doc pages wouldn't be stand-alone any more and would not
   be properly formatted without the web server.  One way to do it is to use
   XHTML frameset/frame elements on the website so that the modules' 
   documentation is incorporated into the web site. This allows the modules'
   documentation to be their own complete pages and not fragments with SSI.
   This allows us to retain the web site "shell" (top and left bars) while 
   also making the documentation stand alone in each module.

2. Many of the documents use keywords for things like Date, Author, Revision,
   etc. For example, the timestamp at the bottom of the LLVM documentation. 
   Unfortunately, when Subversion serves these pages directly, it doesn't 
   expand the keywords (e.g. $Date$). Consequently, we need to check out the
   documentation for presentation on the web site. This is not how it is
   currently arranged.

I'm sure there's much more to discuss.



------- You are receiving this mail because: -------
You are on the CC list for the bug, or are watching someone who is.