bixbite 0.1.0

data/template/assets/naturaldocs/NaturalDocs/Info/File Parsing.txt

@@ -0,0 +1,83 @@
+
+    Architecture: File Parsing
+
+####################################################################################
+
+    This is the architecture and code path for general file parsing.  We pick it up at <NaturalDocs::Parser->Parse()> because we're not interested in how the files are gathered and their languages determined for the purposes of this document.  We are just interested in the process each individual file goes through when it's decided that it should be parsed.
+
+
+
+    Stage: Preparation and Differentiation
+    _______________________________________________________________________________________________________
+
+    <NaturalDocs::Parser->Parse()> can be called from one of two places, <NaturalDocs::Parser->ParseForInformation()> and <NaturalDocs::Parser->ParseForBuild()>, which correspond to the parsing and building phases of Natural Docs.  There is no noteworthy work done in either of them before they call Parse().
+
+
+    Stage: Basic File Processing
+    _______________________________________________________________________________________________________
+
+    The nitty-gritty file handling is no longer done in <NaturalDocs::Parser> itself due to the introduction of full language support in 1.3, as it required two completely different code paths for full and basic language support.  Instead it's handled in NaturalDocs::Languages::Base->ParseFile(), which is really a virtual function that leads to <NaturalDocs::Languages::Simple->ParseFile()> for basic language support or a version appearing in a package derived from <NaturalDocs::Languages::Advanced> for full language support.
+
+    The mechinations of how these functions work is for another document, but their responsibility is to feed all comments Natural Docs should be interested in back to the parser via <NaturalDocs::Parser->OnComment()>.
+
+
+    Stage: Comment Processing
+    _______________________________________________________________________________________________________
+
+    <NaturalDocs::Parser->OnComment()> receives the comment sans comment symbols, since that's language specific.  All comment symbols are replaced by spaces in the text instead of removed so any indentation is properly preserved.  Also passed is whether it's a JavaDoc styled comment, as that varies by language as well.
+
+    OnComment() runs what it receives through <NaturalDocs::Parser->CleanComment()> which normalizes the text by removing comment boxes and horizontal lines, expanding tabs, etc.
+
+
+    Stage: Comment Type Determination
+    _______________________________________________________________________________________________________
+
+    OnComment() sends the comment to <NaturalDocs::Parser::Native->IsMine()> to test if it's definitely Natural Docs content, such as by starting with a recognized header line.  If so, it sends it to <NaturalDocs::Parser::Native->ParseComment()>.
+
+    If not, OnComment() sends the comment to <NaturalDocs::Parser::JavaDoc->IsMine()> to test if it's definitely JavaDoc content, such as by having JavaDoc tags.  If so, it sends it to <NaturalDocs::Parser::JavaDoc->ParseComment()>.
+
+    If not, the content is ambiguous.  If it's a JavaDoc-styled comment it goes to <NaturalDocs::Parser::Native->ParseComment()>  to be treated as a headerless Natural Docs comment.  It is ignored otherwise, which lets normal comments slip through.  Note that it's only ambiguous if neither parser claims it; there's no test to see if they both do.  Instead Natural Docs always wins.
+
+    We will not go into the JavaDoc code path for the purposes of this document.  It simply converts the JavaDoc comment into <NDMarkup> as best it can, which will never be perfectly, and adds a <NaturalDocs::Parser::ParsedTopic> to the list for that file.  Each of those ParsedTopics will be headerless as indicated by having an undefined <NaturalDocs::Parser::ParsedTopic->Title()>.
+
+
+    Stage: Native Comment Parsing
+    _______________________________________________________________________________________________________
+
+    At this point, parsing is handed off to <NaturalDocs::Parser::Native->ParseComment()>.  It searches for header lines within the comment and divides the content into individual topics.  It also detects (start code) and (end) sections so that anything that would normally be interpreted as a header line can appear there without breaking the topic.
+
+    The content between the header lines is sent to <NaturalDocs::Parser::Native->FormatBody()> which handles all the block level formatting such as paragraphs, bullet lists, and code sections.  That function in turn calls <NaturalDocs::Parser::Native->RichFormatTextBlock()> on certain snippets of the text to handle all inline formatting, such as bold, underline, and links, both explicit and automatic.
+
+    <NaturalDocs::Parser::Native->ParseComment()> then has the body in <NDMarkup> so it makes a <NaturalDocs::Parser::ParsedTopic> to add to the list.  It keeps track of the scoping via topic scoping, regardless of whether we're using full or basic language support.  Headerless topics are given normal scope regardless of whether they might be classes or other scoped types.
+
+
+    Group: Post Processing
+    _______________________________________________________________________________________________________
+
+    After all the comments have been parsed into ParsedTopics and execution has been returned to <NaturalDocs::Parser->Parse()>, it's time for some after the fact cleanup.  Some things are done like breaking topic lists, determining the menu title, and adding automatic group headings that we won't get into here.  There are two processes that are very relevant though.
+
+
+    Stage: Repairing Packages
+    _______________________________________________________________________________________________________
+
+    If the file we parsed had full language support, the <NaturalDocs::Languages::Advanced> parser would have done more than just generate various OnComment() calls.  It would also return a scope record, as represented by <NaturalDocs::Languages::Advanced::ScopeChange> objects, and a second set of ParsedTopics it extracted purely from the code, which we'll refer to as autotopics.  The scope record shows, purely from the source, what scope each line of code appears in.  This is then combined with the topic scoping to update ParsedTopics that come from the comments in the function <NaturalDocs::Parser->RepairPackages()>.
+
+    If a comment topic changes the scope, that's honored until the next autotopic or scope change from the code.  This allows someone to document a class that doesn't appear in the code purely with topic scoping without throwing off anything else.  Any other comment topics have their scope changed to the current scope no matter how it's arrived at.  This allows someone to manually document a function without manually documenting the class and still have it appear under that class.  The scope record will change the scope to part of that class even if topic scoping did not.  Essentially the previous topic scoping is thrown out, which I guess is something that can be improved.
+
+    None of this affects the autotopics, as they are known to have the correct scoping since they are gleaned from the code with a dedicated parser.  Wouldn't there be duplication of manually documented code elements, which would appear both in the autotopics and in the comment topics?  Yes.  That brings us to our next stage, which is...
+
+
+    Stage: Merging Auto Topics
+    _______________________________________________________________________________________________________
+
+    As mentioned above, ParseFile() also returns a set of ParsedTopics gleaned from the code called autotopics.  The function <NaturalDocs::Parser->MergeAutoTopics()> merges this list with the comment topics.
+
+    The list is basically merged by line number.  Since named topics should appear directly above the thing that they're documenting, topics are tested that way and combined into one if they match.  The description and title of the comment topic is merged with the prototype of the autotopic.  JavaDoc styled comments are also merged in this function, as they should appear directly above the code element they're documenting.  Any headerless topics that don't, either by appearing past the last autotopic or above another comment topic, are discarded.
+
+
+    Stage: Conclusion
+    _______________________________________________________________________________________________________
+
+    Thus ends all processing by <NaturalDocs::Parser->Parse()>.  The file is now a single list of <NaturalDocs::Parser::ParsedTopics> with all the body content in <NDMarkup>.  If we were using <NaturalDocs::Parser->ParseForBuild()>, that's pretty much it and it's ready to be converted into the output format.  If we were using <NaturalDocs::Parser->ParseForInformation()> though, the resulting file is scanned for all relevant information to feed into other packages such as <NaturalDocs::SymbolTable>.
+
+    Note that no prototype processing was done in this process, only the possible tranferring of prototypes from one ParsedTopic to another when merging autotopics with comment topics.  Obtaining prototypes and formatting them is handled by <NaturalDocs::Languages::Simple> and <NaturalDocs::Languages::Advanced> derived packages.

data/template/assets/naturaldocs/NaturalDocs/Info/HTMLTestCases.pm

@@ -0,0 +1,269 @@
+###############################################################################
+#
+#   File: Browser Testing
+#
+###############################################################################
+#
+#   This file tests Natural Docs' generated output.  Particularly useful when testing various browsers.
+#
+###############################################################################
+
+# This file is part of Natural Docs, which is Copyright (C) 2003-2008 Greg Valure
+# Natural Docs is licensed under the GPL
+
+use strict;
+use integer;
+
+
+#
+#   About: Browsers
+#
+#   The specific browser versions tested are below.  Everything is tested on Windows Vista unless otherwise noted.
+#
+#   Firefox 2.0.0.10 - 2.0 released October 2006.
+#   Firefox 1.5.0.8 - 1.5 released Novemer 2005.
+#   Firefox 1.0.8 - 1.0 released November 2004.  Not critical to support.
+#
+#   IE 7.0 - 7.0 released October 2006.
+#   IE 6.0 - 6.0 released August 2001.  Tested on Windows XP SP2 via Virtual PC.
+#
+#	Safari 3.0.4 - 3.0 released June 2007.  Tested Windows version.
+#	Safari 2.0.4 - 2.0 released April 2005.  Tested on Mac OS X 10.4 Tiger.
+#
+#   Opera 9.02 - 9.0 released June 2006.
+#   Opera 8.54 - 8.5 released September 2005.
+#   Opera 8.02 - 8.0 released April 2005.
+#   Opera 7.51 - 7.5 released around August 2004 I think.  Not critical to support.
+#   Opera 7.02 - 7.0 released January 2003.  Not critical to support.
+#
+#   Konqueror 3.5.5 - Tested on openSUSE 10.2 via VMware Player.
+#
+
+
+###############################################################################
+# Group: Search
+
+#
+#   Topic: Unframed HTML Search
+#
+#   Tests:
+#
+#       - Make sure the search box appears and disappears correctly on hover.
+#       - Type to bring up results.  Type further to narrow them.  Narrow until there's no results.
+#       - Backspace to bring the results back.  Backspacing to empty closes the results.
+#       - Type to bring up results with a different first letter.  (Tests iframe content switch.)
+#       - Type *Z* to bring up empty page when there's nothing with that first letter.  (Tests generic no results page.)
+#       - Type *Name* in Everything search to test expanding and collapsing, especially between two that differ only by case.
+#       - Change filter to *Functions* to test changing filter while results are open.  Change to *Types* to switch to one with
+#         no results.
+#       - Test Close button on results.  Should deactivate panel as well.
+#       - Clicking away should deactivate panel if the box is empty, not have an effect if there are results open.
+#       - Text should always change back to "Search" when deactivating.
+#
+#   Results:
+#
+#       Firefox 2.0  - OK
+#       Firefox 1.5  - OK
+#       Firefox 1.0  - OK
+#
+#       IE 7.0  - OK
+#       IE 6.0  - Functionally OK.  Search panel doesn't activate on hover.  Works fine when clicked.
+#
+#		Safari 3.0  - OK
+#		Safari 2.0  - *Broken.*  Results panel doesn't show up.  Border around deactivated search box.
+#
+#       Opera 9.0  - OK
+#       Opera 8.5  - OK
+#       Opera 8.0  - OK
+#       Opera 7.5  - Functionally OK.  Search panel has sunken border when deactivated, minor pixel shifting.
+#       Opera 7.0  - *Broken.*  Completely.
+#
+#       Konqueror 3.5  - *Broken.*  Results panel doesn't show up.  Seems to fail on "resultsFrame = window.frames.MSearchResults;"
+#
+
+#
+#   Topic: Framed HTML Search
+#
+#   Tests:
+#
+#       - Make sure the search box appears and disappears correctly on hover.
+#       - Type to bring up results on right.  Type further to narrow them.  Narrow until there's no results.
+#       - Backspace to bring the results back.
+#       - Type to bring up results with a different first letter.  (Tests frame content switch.)
+#       - Type *Z* to bring up empty page when there's nothing with that first letter.  (Tests generic no results page.)
+#       - Type *Name* in Everything search to see that there's no collapsing in this mode.
+#       - Change filter to *Functions* to test changing filter while results are open.  Change to *Types* to switch to one with
+#         no results.
+#       - Clicking away should deactivate panel.
+#       - Clicking a result should deactivate panel and show up in correct frame.
+#       - Text should always change back to "Search" when deactivating.
+#
+#   Results:
+#
+#       Firefox 2.0  - OK
+#       Firefox 1.5  - OK
+#       Firefox 1.0  - OK
+#
+#       IE 7.0  - OK
+#       IE 6.0  - Functionally OK.  Search panel doesn't activate on hover, is a little wide.  Works fine when clicked.
+#
+#		Safari 3.0  - OK
+#		Safari 2.0  - Functionally OK.  Has a sunken border around the deactivated seach field.
+#
+#       Opera 9.0  - OK
+#       Opera 8.5  - OK
+#       Opera 8.0  - OK
+#       Opera 7.5  - Functionally OK.  Search panel has sunken border when deactivated, minor pixel shifting.
+#       Opera 7.0  - *Broken.*
+#
+#       Konqueror 3.5  - Functionally OK.  Panel doesn't reset and deactivate when clicking a result link.
+#
+
+
+###############################################################################
+# Group: Other
+
+#
+#   Topic: Images
+#
+#	Tests:
+#
+#   - Here is an embedded image on its own line.
+#
+#   (see images/logo.png)
+#
+#   - Here is a reference in the middle of a sentence, in the middle of a bullet list: (see images/logo.png)  It should have been
+#     converted to a link with the image appearing below the bullet list and the file name used as a caption.  Make sure the
+#     caption positions correctly.
+#   - Here's a link to a non-existent image, which should appear literally: (see images/doesntexist.jpg)
+#   - Here is an embedded image that doesn't exist on it's own line.
+#
+#   (see images/doesntexist.png)
+#
+#   - Here is a link using the "(see)" syntax which shouldn't be interpreted as an image link because it doesn't end with an
+#     acceptable extension.  Also, links should still resolve because of that.  (see <Framed HTML Search>)
+#
+#	Results:
+#
+#       Firefox 2.0  - OK
+#       Firefox 1.5  - OK
+#       Firefox 1.0  - OK
+#
+#       IE 7.0  - OK
+#       IE 6.0  - OK
+#
+#		Safari 3.0  - OK
+#		Safari 2.0  - OK
+#
+#       Opera 9.0  - OK
+#       Opera 8.5  - OK
+#       Opera 8.0  - OK
+#       Opera 7.5  - OK
+#       Opera 7.0  - OK
+#
+#       Konqueror 3.5  - OK
+
+
+#
+#	Topic: Prototypes and Tooltips
+#
+#	Hover over <NaturalDocs::Parser::JavaDoc->ParseComment()> and <NaturalDocs::Parser::JavaDoc->IsMine()>
+#
+#	Tests:
+#
+#		- A tooltip should appear about a second after you hover over the link above.
+#		- It should go away when you move the cursor away.
+#		- It shoud be positioned directly underneath with a slight gap.
+#		- The prototype should be formatted cleanly with each parameter on its own line and aligned in columns.
+#		- The asterisk should be in a separate column.
+#		- Test it with the link too close to the edge of the window so the pop-up has to shift left to fit.
+#
+#	Results:
+#
+#       Firefox 2.0  - OK
+#       Firefox 1.5  - OK
+#       Firefox 1.0  - OK
+#
+#       IE 7.0  - OK
+#       IE 6.0  - OK
+#
+#		Safari 3.0  - OK
+#		Safari 2.0  - OK
+#
+#       Opera 9.0  - OK.  Has its own tooltips turned on by default which can cover it up though.
+#       Opera 8.5  - OK.  Has its own tooltips turned on by default which can cover it up though.
+#       Opera 8.0  - OK.  Has its own tooltips turned on by default which can cover it up though.
+#       Opera 7.5  - OK.  Has its own tooltips turned on by default which can cover it up though.
+#       Opera 7.0  - *Broken.*  Usually works, if the window is too narrow may collapse completely.
+#
+#       Konqueror 3.5  - OK
+#
+
+
+#
+#	Topic: Long code block scrolling
+#
+#	Go to <Prototype Parameter Styles>.
+#
+#	Tests:
+#
+#		- Shrink the browser window so that a line extends past the end of it.  Only the line should have a scrollbar, not the
+#		  entire page.
+#		- Expand the browser window.  The scrollbar should disappear.
+#
+#	Results:
+#
+#       Firefox 2.0  - OK
+#       Firefox 1.5  - OK
+#       Firefox 1.0  - OK
+#
+#       IE 7.0  - OK
+#       IE 6.0  - OK
+#
+#		Safari 3.0  - OK
+#		Safari 2.0  - OK
+#
+#       Opera 9.0  - OK
+#       Opera 8.5  - OK
+#       Opera 8.0  - OK
+#       Opera 7.5  - OK
+#       Opera 7.0  - OK
+#
+#       Konqueror 3.5  - OK
+#
+
+
+#
+#	Topic: Menu and Class Hierarchies
+#
+#	Go to <NaturalDocs::Languages::Simple>.
+#
+#	Tests:
+#
+#		- Class hierarchy should look okay.
+#		- Make sure the menu hierarchy opens up on its own when the page is loaded.
+#		- You should be able to click on groups to open and close them.
+#
+#	Results:
+#
+#       Firefox 2.0  - OK
+#       Firefox 1.5  - OK
+#       Firefox 1.0  - OK
+#
+#       IE 7.0  - OK
+#       IE 6.0  - OK
+#
+#		Safari 3.0  - OK
+#		Safari 2.0  - OK
+#
+#       Opera 9.0  - OK
+#       Opera 8.5  - OK
+#       Opera 8.0  - OK
+#       Opera 7.5  - OK
+#       Opera 7.0  - OK
+#
+#       Konqueror 3.5  - OK
+#
+
+
+1;

data/template/assets/naturaldocs/NaturalDocs/Info/Languages.txt

@@ -0,0 +1,107 @@
+
+    Title: Language Notes
+_______________________________________________________________________________
+
+    This is more for my personal reference than anything else.
+
+
+    ___________________________________________________________________________
+
+    Topic: Prototype Parameter Styles
+    ___________________________________________________________________________
+
+    Parameters via Commas, Typed via Spaces:
+
+        > FunctionName ( type indentifier, type identifier = value, modifier type identifier )
+        > FunctionName ( indentifier, identifier = value )
+
+        The general idea is that parameters are separated by commas.  Identifiers cannot contain spaces.  Types and modifiers,
+        if available, are separated from the identifiers with spaces.  There may be an equals sign to set the default value.
+
+        So parsing means splitting by commas, stripping everything past an equals sign for the default value, stripping everything
+        after the last space for the identifier, and the rest is the type.  If there are no internal spaces after the default value is
+        stripped, it's all identifier.
+
+        Note that internal parenthesis, brackets, braces, and angle brackets should be parsed out.  They may be present in default
+        values or types and any commas and equal signs in them should not be included.
+
+        Applies to C++, Java, C#, JavaScript, Python, PHP, Ruby.
+
+        Applies to Perl as well, even though it doesn't have any real parameter declaration structure.  Just adding it with comments
+        is fine.
+
+    Parameters via Semicolons and Commas, Typed via Colons:
+
+        > FunctionName ( identifier: type; identifier, identifier: type; identifier: type := value )
+
+        Parameters via semicolons, types via colons.  However, there can be more than one parameter per type via commas.
+        Default values via colon-equals.
+
+        Applies to Pascal, Ada.
+
+
+    SQL:
+
+        > FunctionName ( identifier type, identifier modifier type, identifier type := value )
+
+        Parameters separated by commas.  Identifiers come before the types and are separated by a space.  Default values are
+        specified with colon-equals.
+
+        > FunctionName @identifier type, @dentifier modifier type, @identifier type = value
+
+        Microsoft's SQL uses equals instead of colon-equals, doesn't need parenthesis, and starts its parameter names with an @
+        symbol.
+
+
+    Visual Basic:
+
+        > FunctionName ( modifiers identifier as type, identifier = value )
+
+        Parameters separated by commas.  Default values via equals.  However, any number of modifiers may appear before the
+        identifier.  Those modifiers are ByVal, ByRef, Optional, and ParamArray.
+
+
+    Tcl:
+
+        > FunctionName { identifier identifier { whatever } } { code }
+
+        Identifiers are specified in the first set of braces and have no commas.  However, they can be broken out into sub-braces.
+
+
+    ___________________________________________________________________________
+
+    Topic: Syntax References
+    ___________________________________________________________________________
+
+    C++ - http://www.csci.csusb.edu/dick/c++std/syntax.html
+
+    C# - http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csspec/html/CSharpSpecStart.asp.  Open in IE.
+
+    Java - http://cui.unige.ch/db-research/Enseignement/analyseinfo/
+    Ada - http://cui.unige.ch/db-research/Enseignement/analyseinfo/
+
+    SQL - http://cui.unige.ch/db-research/Enseignement/analyseinfo/,
+             <http://www.cs.umb.edu/cs634/ora9idocs/appdev.920/a96624/13_elems.htm>, or
+             <http://msdn.microsoft.com/library/default.asp?url=/library/en-us/tsqlref/ts_tsqlcon_6lyk.asp?frame=true> (open in IE).
+
+    JavaScript - http://academ.hvcc.edu/~kantopet/javascript/index.php
+
+    Python - http://www.python.org/doc/2.3.4/ref/ref.html
+
+    PHP - http://www.php.net/manual/en/langref.php
+
+    Visual Basic - http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vbls7/html/vbspecstart.asp.  Open in IE.
+
+    Pascal - <http://pages.cpsc.ucalgary.ca/~becker/231/SyntaxDiagrams/pascal-syntax_files/frame.htm>.  Open in IE.
+
+    Ruby - http://www.rubycentral.com/book/
+
+    ActionScript 2 - <http://download.macromedia.com/pub/documentation/en/flash/fl8/fl8_as2lr.pdf>
+    ActionScript 3 - <http://download.macromedia.com/pub/documentation/en/flex/2/prog_actionscript30.pdf>
+    E2X - http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-357.pdf
+
+    R - Somewhere on http://www.r-project.org.
+
+    ColdFusion - <http://livedocs.macromedia.com/coldfusion/6/Developing_ColdFusion_MX_Applications_with_CFML/contents.htm>
+
+    Eiffel - http://www.gobosoft.com/eiffel/syntax/