The multilang-documentation Reference Manual

This is the multilang-documentation Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Feb 15 06:58:04 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 multilang-documentation

A drop-in replacement for CL:DOCUMENTATION providing multi-language docstrings

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

https://github.com/Shinmera/multilang-documentation

License

zlib

Version

1.0.0

Dependencies
  • documentation-utils (system).
  • language-codes (system).
  • system-locale (system).
Source

multilang-documentation.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 multilang-documentation/multilang-documentation.asd

Source

multilang-documentation.asd.

Parent Component

multilang-documentation (system).

ASDF Systems

multilang-documentation.


3.1.2 multilang-documentation/package.lisp

Source

multilang-documentation.asd.

Parent Component

multilang-documentation (system).

Packages

multilang-documentation.


3.1.3 multilang-documentation/canonical.lisp

Dependency

package.lisp (file).

Source

multilang-documentation.asd.

Parent Component

multilang-documentation (system).

Public Interface

canonicalize-doctype (generic function).


3.1.4 multilang-documentation/language.lisp

Dependency

canonical.lisp (file).

Source

multilang-documentation.asd.

Parent Component

multilang-documentation (system).

Public Interface
Internals

3.1.5 multilang-documentation/drop-in.lisp

Dependency

language.lisp (file).

Source

multilang-documentation.asd.

Parent Component

multilang-documentation (system).

Public Interface

3.1.6 multilang-documentation/documentation.lisp

Dependency

drop-in.lisp (file).

Source

multilang-documentation.asd.

Parent Component

multilang-documentation (system).


4 Packages

Packages are listed by definition order.


4.1 multilang-documentation

Source

package.lisp.

Nickname

org.shirakumo.multilang-documentation

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *language*

This variable holds the user’s chosen language.

Its default value is automatically chosen according to the system’s configured language.

The value held by this should be a LANGUAGE instance.

See SYSTEM-LOCALE:LANGUAGE
See LANGUAGE

Package

multilang-documentation.

Source

language.lisp.


5.1.2 Ordinary functions

Function: documentation (object type &key lang)

Retrieve the documentation string for the given object and type.

You may optionally specify the language that the docstring should be in. The default language is *LANGUAGE*, which
will typically be automatically configured according to your system’s locale settings.

When reading a docstring, if there is no documentation stored specifically for the given language, and the language is eq to *LANGUAGE*, CL:DOCUMENTATION is consulted instead.

When writing a docstring, if the language is eq to *LANGUAGE*, the docstring is also written to CL:DOCUMENTATION. Note that your implementation might not store docstrings for unknown documentation specifiers, but the language object will always do so regardless. Either way, this mechanism is mostly provided as a best-effort backwards compatibility to users of CL:DOCUMENTATION.

See CL:DOCUMENTATION
See DOCUMENTATION*
See *LANGUAGE*

Package

multilang-documentation.

Source

drop-in.lisp.

Function: (setf documentation) (object type &key lang)
Package

multilang-documentation.

Source

drop-in.lisp.


5.1.3 Generic functions

Generic Function: canonicalize-doctype (object type)

This function should return a canonical representation for the given documentation specifier.

Some documentation strings can be referred to by different
specifiers. For instance:

- (#<function foo> T)
- (#<function foo> ’function)
- (’foo ’function)

All refer to the same documentation string. This function
should return a value that identifies a docstring for the
given object and type. The same (under EQUAL) value must
be returned for any object and type combinations that
should refer to the same docstring.

You should add appropriate methods to this function for
custom documentation specifiers / types.

See CL:EQUAL

Package

multilang-documentation.

Source

canonical.lisp.

Methods
Method: canonicalize-doctype ((object symbol) (type (eql type)))
Method: canonicalize-doctype ((object symbol) (type (eql structure)))
Method: canonicalize-doctype ((object list) (type (eql compiler-macro)))
Method: canonicalize-doctype ((object list) (type (eql function)))
Method: canonicalize-doctype ((object symbol) (type (eql compiler-macro)))
Method: canonicalize-doctype ((object symbol) (type (eql function)))
Method: canonicalize-doctype ((object structure-class) type)
Method: canonicalize-doctype ((object standard-class) type)
Method: canonicalize-doctype ((object standard-method) type)
Method: canonicalize-doctype ((object method-combination) type)
Method: canonicalize-doctype ((object package) type)
Method: canonicalize-doctype ((object function) type)
Method: canonicalize-doctype (object type)
Generic Function: documentation* (object type lang)

Access the docstring for the given object, type and language.

If LANGUAGE is not an instance of LANGUAGE, the value is coerced to a LANGUAGE instance by way of the LANGUAGE function.

When reading a docstring from an inexistent language, NIL is returned as well as a NO-SUCH-LANGUAGE instance as the secondary value.

When writing a docstring to an inexistent language, a new language instance is automatically created by way of the :IF-DOES-NOT-EXIST :CREATE argument to the LANGUAGE function.

If you are implementing your own subclass of LANGUAGE that bypasses the DOCUMENTATION-STORAGE mechanism, you should add methods to this function that provide the desired behaviour.

See LANGUAGE
See CANONICALIZE-DOCTYPE
See DOCUMENTATION-STORAGE
See DOCUMENTATION

Package

multilang-documentation.

Source

drop-in.lisp.

Methods
Method: documentation* (object type identifier)
Method: documentation* (object type (language language))
Generic Function: (setf documentation*) (object type language)
Package

multilang-documentation.

Methods
Method: (setf documentation*) (object type identifier)
Source

drop-in.lisp.

Method: (setf documentation*) (object type (language language))
Source

drop-in.lisp.

Generic Reader: documentation-storage (language)

Returns the hash-table for the docstring storage of the language.

This hash-table must be using the EQUAL test.
Keys are canonical docstring identifiers as returned by CANONICALIZE-DOCTYPE. Values are docstrings.

See CANONICALIZE-DOCTYPE
See DOCUMENTATION*

Package

multilang-documentation.

Source

language.lisp.

Methods
Reader Method: documentation-storage ((simple-language simple-language))

automatically generated reader method

Target Slot

%documentation-storage.

Generic Reader: identifier (language)

Returns the identifier of the object.

See NO-SUCH-LANGUAGE
See SIMPLE-LANGUAGE

Package

multilang-documentation.

Source

language.lisp.

Methods
Reader Method: identifier ((simple-language simple-language))

automatically generated reader method

Target Slot

%identifier.

Reader Method: identifier ((condition no-such-language))
Target Slot

identifier.

Generic Function: language (identifier &key if-does-not-exist)

Returns the language object referred to by the given identifier.

If a LANGUAGE instance is passed, the language instance is simply returned directly.

IF-DOES-NOT-EXIST can be one of the following values, designating the behaviour if no language for the given identifier can be found:

:CREATE — A new SIMPLE-LANGUAGE instance is created and associated with the identifier.
:ERROR — An error of type NO-SUCH-LANGUAGE is signalled. The following restarts will be available:
USE-VALUE — Return the given restart value. STORE-VALUE — Associate the given restart value with the identifier and return it. MAKE-INSTANCE — This behaviour is the same as :if-does-not-exist :create
NIL — Returns NIL.

When USE-VALUE or STORE-VALUE are called interactively, the value is read and evaluated, and then passed through LANGUAGE to potentially coerce it to an existing language object.

See *LANGUAGES*
See SIMPLE-LANGUAGE

Package

multilang-documentation.

Source

language.lisp.

Methods
Method: language ((language language) &key if-does-not-exist)
Method: language ((identifier symbol) &key if-does-not-exist)
Method: language ((identifier string) &key if-does-not-exist)
Generic Function: (setf language) (identifier)
Package

multilang-documentation.

Methods
Method: (setf language) ((identifier symbol))
Source

language.lisp.

Method: (setf language) ((identifier string))
Source

language.lisp.


5.1.4 Standalone methods

Method: make-load-form ((language simple-language) &optional env)
Source

language.lisp.

Method: print-object ((language simple-language) stream)
Source

language.lisp.


5.1.5 Conditions

Condition: no-such-language

Error signalled when an inexistent language is referenced.

See IDENTIFIER
See LANGUAGE

Package

multilang-documentation.

Source

language.lisp.

Direct superclasses

error.

Direct methods

identifier.

Direct slots
Slot: identifier
Initargs

:identifier

Readers

identifier.

Writers

This slot is read-only.


5.1.6 Classes

Class: language

Superclass for all languages that can store docstrings.

Instances of this class can be used to store documentation strings.

See DOCUMENTATION-STORAGE
See LANGUAGE
See DOCUMENTATION*

Package

multilang-documentation.

Source

language.lisp.

Direct subclasses

simple-language.

Direct methods
Class: simple-language

A simple language object that keeps its identifier and a docstring storage.

See LANGUAGE
See IDENTIFIER
See DOCUMENTATION-STORAGE
See LANGUAGE

Package

multilang-documentation.

Source

language.lisp.

Direct superclasses

language.

Direct methods
Direct Default Initargs
InitargValue
:identifier(error identifier required.)
Direct slots
Slot: %identifier
Initargs

:identifier

Readers

identifier.

Writers

This slot is read-only.

Slot: %documentation-storage
Initform

(make-hash-table :test (quote equal))

Readers

documentation-storage.

Writers

This slot is read-only.


5.2 Internals


5.2.1 Special variables

Special Variable: *languages*

This hash table keeps records of language identifiers to language instances.

Language identifiers are the same under EQUALP.

See LANGUAGE

Package

multilang-documentation.

Source

language.lisp.


5.2.2 Ordinary functions

Function: prompt-language ()

Prompts for a new language object.

Reads and evaluates a value from *QUERY-IO*, then passes it to LANGUAGE, and finally returns that result in a list.

This should be used as an interactive restart function.

See CL:*QUERY-IO*
See LANGUAGE

Package

multilang-documentation.

Source

language.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
C   D   F   G   I   L   M   P  
Index Entry  Section

(
(setf documentation): Public ordinary functions
(setf documentation*): Public generic functions
(setf documentation*): Public generic functions
(setf documentation*): Public generic functions
(setf language): Public generic functions
(setf language): Public generic functions
(setf language): Public generic functions

C
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions
canonicalize-doctype: Public generic functions

D
documentation: Public ordinary functions
documentation*: Public generic functions
documentation*: Public generic functions
documentation*: Public generic functions
documentation-storage: Public generic functions
documentation-storage: Public generic functions

F
Function, (setf documentation): Public ordinary functions
Function, documentation: Public ordinary functions
Function, prompt-language: Private ordinary functions

G
Generic Function, (setf documentation*): Public generic functions
Generic Function, (setf language): Public generic functions
Generic Function, canonicalize-doctype: Public generic functions
Generic Function, documentation*: Public generic functions
Generic Function, documentation-storage: Public generic functions
Generic Function, identifier: Public generic functions
Generic Function, language: Public generic functions

I
identifier: Public generic functions
identifier: Public generic functions
identifier: Public generic functions

L
language: Public generic functions
language: Public generic functions
language: Public generic functions
language: Public generic functions

M
make-load-form: Public standalone methods
Method, (setf documentation*): Public generic functions
Method, (setf documentation*): Public generic functions
Method, (setf language): Public generic functions
Method, (setf language): Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, canonicalize-doctype: Public generic functions
Method, documentation*: Public generic functions
Method, documentation*: Public generic functions
Method, documentation-storage: Public generic functions
Method, identifier: Public generic functions
Method, identifier: Public generic functions
Method, language: Public generic functions
Method, language: Public generic functions
Method, language: Public generic functions
Method, make-load-form: Public standalone methods
Method, print-object: Public standalone methods

P
print-object: Public standalone methods
prompt-language: Private ordinary functions


A.4 Data types

Jump to:   C   D   F   L   M   N   P   S  
Index Entry  Section

C
canonical.lisp: The multilang-documentation/canonical․lisp file
Class, language: Public classes
Class, simple-language: Public classes
Condition, no-such-language: Public conditions

D
documentation.lisp: The multilang-documentation/documentation․lisp file
drop-in.lisp: The multilang-documentation/drop-in․lisp file

F
File, canonical.lisp: The multilang-documentation/canonical․lisp file
File, documentation.lisp: The multilang-documentation/documentation․lisp file
File, drop-in.lisp: The multilang-documentation/drop-in․lisp file
File, language.lisp: The multilang-documentation/language․lisp file
File, multilang-documentation.asd: The multilang-documentation/multilang-documentation․asd file
File, package.lisp: The multilang-documentation/package․lisp file

L
language: Public classes
language.lisp: The multilang-documentation/language․lisp file

M
multilang-documentation: The multilang-documentation system
multilang-documentation: The multilang-documentation package
multilang-documentation.asd: The multilang-documentation/multilang-documentation․asd file

N
no-such-language: Public conditions

P
Package, multilang-documentation: The multilang-documentation package
package.lisp: The multilang-documentation/package․lisp file

S
simple-language: Public classes
System, multilang-documentation: The multilang-documentation system