Merge remote-tracking branch 'upstream/master'

Conflicts:
	include/lynx.h

doc/apple2.sgml

@@ -332,6 +332,7 @@ usage.
 <item>_datetime
 <item>allow_lowercase
 <item>beep
+<item>dir_entry_count
 <item>get_ostype
 <item>gmtime_dt
 <item>mktime_dt

doc/apple2enh.sgml

@@ -332,6 +332,7 @@ usage.
 <item>_filetype
 <item>_datetime
 <item>beep
+<item>dir_entry_count
 <item>get_ostype
 <item>gmtime_dt
 <item>mktime_dt

doc/ca65.sgml

@@ -1059,7 +1059,7 @@ The namespace token (<tt/::/) is used to access other scopes:
         .endscope
 
                 ...
-                lda     foo::bar        ; Access foo in scope bar
+                lda     #foo::bar        ; Access bar in scope foo
 </verb></tscreen>
 
 The only way to deny access to a scope from the outside is to declare a scope
@@ -3897,7 +3897,7 @@ See: <tt><ref id=".ASCIIZ" name=".ASCIIZ"></tt>,<tt><ref id=".BYTE" name=".BYTE"
 
   Reserve storage. The command is followed by one or two constant
   expressions. The first one is mandatory and defines, how many bytes of
-  storage should be defined. The second, optional expression must by a
+  storage should be defined. The second, optional expression must be a
   constant byte value that will be used as value of the data. If there
   is no fill value given, the linker will use the value defined in the
   linker configuration file (default: zero).

doc/cc65.sgml

@@ -1370,7 +1370,7 @@ sequences of the input.
   Example:
   <tscreen><verb>
   /* Use a space wherever an 'a' occurs in ISO-8859-1 source */
-  #pragma charmap (0x61, 0x20);
+  #pragma charmap (0x61, 0x20)
   </verb></tscreen>
 
 

doc/funcref.sgml

@@ -97,6 +97,7 @@ function.
 <item>_dos_type
 <item>allow_lowercase
 <item><ref id="beep" name="beep">
+<item><ref id="dir_entry_count" name="dir_entry_count">
 <item><ref id="get_ostype" name="get_ostype">
 <item><ref id="gmtime_dt" name="gmtime_dt">
 <item><ref id="mktime_dt" name="mktime_dt">
@@ -109,6 +110,7 @@ function.
 <itemize>
 <item>_dos_type
 <item><ref id="beep" name="beep">
+<item><ref id="dir_entry_count" name="dir_entry_count">
 <item><ref id="get_ostype" name="get_ostype">
 <item><ref id="gmtime_dt" name="gmtime_dt">
 <item><ref id="mktime_dt" name="mktime_dt">
@@ -3524,6 +3526,25 @@ used in presence of a prototype.
 </quote>
 
 
+<sect1>dir_entry_count<label id="dir_entry_count"><p>
+
+<quote>
+<descrip>
+<tag/Function/Returns the number of entries in the directory.
+<tag/Header/<tt/<ref id="apple2.h" name="apple2.h">/
+<tag/Declaration/<tt/unsigned int __fastcall__ dir_entry_count(DIR *dir);/
+<tag/Description/<tt/dir_entry_count/ is machine dependent and does not exist for
+all supported targets. If it exists, it returns the number of active
+(non-deleted) files and directories in the directory.
+<tag/Notes/<itemize>
+<item>The function does not exist on all platforms.
+</itemize>
+<tag/Availability/cc65 (not all platforms)
+<tag/Example/None.
+</descrip>
+</quote>
+
+
 <sect1>div<label id="div"><p>
 
 <quote>

doc/ld65.sgml

@@ -1180,6 +1180,202 @@ The ZPSAVE segment contains the original values of the zeropage locations used
 by the ZEROPAGE segment. It is placed in its own segment because it must not be
 initialized.
 
+<sect>Debug Info<p>
+
+The debug info and the API mirrors closely the items available in the sources
+used to build an executable. To use the API efficiently, it is necessary to
+understand from which blocks the information is built.
+
+<itemize>
+<item>  Libraries
+<item>  Lines
+<item>  Modules
+<item>  Scopes
+<item>  Segments
+<item>  Source files
+<item>  Spans
+<item>  Symbols
+<item>  Types
+</itemize>
+
+Each item of each type has something like a primary index called an 'id'.
+The ids can be thought of as array indices, so looking up something by its
+id is fast. Invalid ids are marked with the special value CC65_INV_ID.
+Data passed back for an item may contain ids of other objects. A scope for
+example contains the id of the parent scope (or CC65_INV_ID if there is no
+parent scope). Most API functions use ids to lookup related objects.
+
+
+<sect1>Libraries<p>
+
+This information comes from the linker and is currently used in only one
+place:To mark the origin of a module. The information available for a library
+is its name including the path.
+
+<itemize>
+<item> Library id
+<item> Name and path of library
+</itemize>
+
+
+<sect1>Lines<p>
+
+A line is a location in a source file. It is module dependent, which means
+that if two modules use the same source file, each one has its own line
+information for this file. While the assembler has also column information,
+it is dropped early because it would generate much more data. A line may have
+one or more spans attached if code or data is generated.
+
+<itemize>
+<item> Line id
+<item> Id of the source file, the line is from
+<item> The line number in the file (starting with 1)
+<item> The type of the line: Assembler/C source or macro
+<item> A count for recursive macros if the line comes from a macro
+</itemize>
+
+
+<sect1>Modules<p>
+
+A module is actually an object file. It is generated from one or more source
+files and may come from a library. The assembler generates a main scope for
+symbols declared outside user generated scopes. The main scope has an empty name.
+
+<itemize>
+<item> Module id
+<item> The name of the module including the path
+<item> The id of the main source file (the one specified on the command line)
+<item> The id of the library the module comes from, or CC65_INV_ID
+<item> The id of the main scope for this module
+</itemize>
+
+
+<sect1>Scopes<p>
+
+Each module has a main scope where all symbols live, that are specified outside
+other scopes. Additional nested scopes may be specified in the sources. So scopes
+have a one to many relation: Each scope (with the exception of the main scope) has
+exactly one parent and may have several child scopes. Scopes may not cross modules.
+
+<itemize>
+<item> Scope id
+<item> The name of the scope (may be empty)
+<item> The type of the scope: Module, .SCOPE or .PROC, .STRUCT and .ENUM
+<item> The size of the scope (the size of the span for the active segment)
+<item> The id of the parent scope (CC65_INV_ID in case of the main scope)
+<item> The id of the attached symbol for .PROC scopes
+<item> The id of the module where the scope comes from
+</itemize>
+
+
+<sect1>Segment Info<p>
+
+<itemize>
+<item> Segment id
+<item> The name of the segment
+<item> The start address of the segment
+<item> The size of the segment
+<item> The name of the output file, this segment was written to (may be empty)
+<item> The offset of the segment in the output file (only if name not empty)
+<item> The bank number of the segment's memory area
+</itemize>
+
+It is also possible to retrieve the spans for sections (a section is the part of a
+segment that comes from one module). Since the main scope covers a whole module, and
+the main scope has spans assigned (if not empty), the spans for the main scope of a
+module are also the spans for the sections in the segments.
+
+
+<sect1>Source files<p>
+
+Modules are generated from source files. Since some source files are used several times
+when generating a list of modules (header files for example), the linker will merge
+duplicates to reduce redundant information. Source files are considered identical if the
+full name including the path is identical, and the size and time of last modification
+matches. Please note that there may be still duplicates if files are accessed using
+different paths.
+
+<itemize>
+<item> Source file id
+<item> The name of the source file including the path
+<item> The size of the file at the time when it was read
+<item> The time of last modification at the time when the file was read
+</itemize>
+
+
+<sect1>Spans<p>
+
+A span is a small part of a segment. It has a start address and a size. Spans are used
+to record sizes of other objects. Line infos and scopes may have spans attached, so it
+is possible to lookup which data was generated for these items.
+
+<itemize>
+<item> Span id
+<item> The start address of the span. This is an absolute address
+<item> The end address of the span. This is inclusive which means if start==end then => size==1
+<item> The id of the segment were the span is located
+<item> The type of the data in the span (optional, maybe NULL)
+<item> The number of line infos available for this span
+<item> The number of scope infos available for this span
+</itemize>
+
+The last two fields will save a call to cc65_line_byspan or cc65_scope_byspan by providing
+information about the number of items that can be retrieved by these calls.
+
+
+<sect1>Symbols<p>
+
+<itemize>
+<item> Symbol id
+<item> The name of the symbol
+<item> The type of the symbol, which may be label, equate or import
+<item> The size of the symbol (size of attached code or data). Only for labels. Zero if unknown
+<item> The value of the symbol. For an import, this is taken from the corresponding export
+<item> The id of the corresponding export. Only valid for imports, CC65_INV_ID for other symbols
+<item> The segment id if the symbol is segment based. For an import, taken from the export
+<item> The id of the scope this symbols was defined in
+<item> The id of the parent symbol. This is only set for cheap locals and CC65_INV_ID otherwise
+</itemize>
+
+Beware: Even for an import, the id of the corresponding export may be CC65_INV_ID.
+This happens if the module with the export has no debug information. So make sure
+that your application can handle it.
+
+
+<sect1>Types<p>
+
+A type is somewhat special. You cannot retrieve data about it in a similar way as with the other
+items. Instead you have to call a special routine that parses the type data and returns it
+in a set of data structures that can be processed by a C or C++ program.
+
+The type information is language independent and doesn't encode things like 'const' or
+'volatile'. Instead it defines a set of simple data types and a few ways to aggregate
+them (arrays, structs and unions).
+
+Type information is currently generated by the assembler for storage allocating commands
+like .BYTE or .WORD. For example, the assembler code
+
+<tscreen><verb>
+foo:    .byte $01, $02, $03
+</verb></tscreen>
+
+will assign the symbol foo a size of 3, but will also generate a span with a size of 3
+bytes and a type ARRAY[3] OF BYTE.
+Evaluating the type of a span allows a debugger to display the data in the same way as it
+was defined in the assembler source.
+
+<table>
+<tabular ca="clc">
+<bf/Assembler Command/| <bf/Generated Type Information/@<hline>
+.ADDR| ARRAY OF LITTLE ENDIAN POINTER WITH SIZE 2 TO VOID@
+.BYTE| ARRAY OF UNSIGNED WITH SIZE 1@
+.DBYT| ARRAY OF BIG ENDIAN UNSIGNED WITH SIZE 2@
+.DWORD| ARRAY OF LITTLE ENDIAN UNSIGNED WITH SIZE 4@
+.FARADDR| ARRAY OF LITTLE ENDIAN POINTER WITH SIZE 3 TO VOID@
+.WORD| ARRAY OF LITTLE ENDIAN UNSIGNED WITH SIZE 2
+</tabular>
+</table>
+
 
 
 <sect>Copyright<p>