The multilang-documentation Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The multilang-documentation Reference Manual

This is the multilang-documentation Reference Manual, version 1.0.0, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Apr 08 14:39:38 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

About Multilang-Documentation

This library provides a drop-in replacement function for cl:documentation that supports multiple docstrings per-language, allowing you to write documentation that can be internationalised.

How To

If you want to use this library's documentation function instead of cl's, you can simply add this to your package definition:

(:shadowing-import-from #:multilang-documentation #:documentation)

You can also do this at the REPL using shadowing-import:

(shadowing-import 'multilang-documentation:documentation)

The new documentation introduces a :lang keyword argument with which you can specify the language of the docstring. The default language of your system is determined automatically via the available system information. Please consult system-locale for this mechanism. If you would like to force a specific language as the default, you can set the *language* variable like so:

(setf multilang-documentation:*language* 
      (multilang-documentation:language "Japanese" :if-does-not-exist :create))

You may either use a two or three-letter ISO-639 language code keyword, or a full language name as a string to identify the language.

Note that cl:documentation is used as fallback lookup mechanism if the language passed to documentation is *LANGUAGE* (the default).

Also note that documentation can be used as a storage for arbitrary documentation types, unlike cl:documentation which is free to ignore documentation types it doesn't know about. If you do save your own documentation types you should however make sure that the library can canonically identify your docstrings:

Some docstrings can be identified in multiple ways, like (#<function foo> T) and ('foo 'function). canonicalize-doctype exists in order to fix this problem and coerce any kind of combination of object and type parameters into a single, canonical value. This value should be equal to other values be considered the same. For instance, if you have a custom documentation object, you can add a canonicalisation by using something like the following:

(defmethod multilang-documentation:canonicalize-doctype ((object my-type) type)
  object)

(defmethod multilang-documentation:canonicalize-doctype ((name symbol) (type (eql 'my-type)))
  (find-my-type-instance name))

In case you have your own system that deals with languages and would like to integrate this library with it, you should make your languages subclass language, add a method to identifier, and either add a method to documentation-storage, or to documentation* and (setf documentation*) to handle the docstring lookup and storage. Finally, if you would like to override the language lookup mechanism, you should override the string-specialised method on language as well.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 multilang-documentation

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

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

License

Artistic

Description

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

Version

1.0.0

Dependencies
Source

multilang-documentation.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 multilang-documentation.asd

Location

multilang-documentation.asd

Systems

multilang-documentation (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 multilang-documentation/package.lisp

Parent

multilang-documentation (system)

Location

package.lisp

Packages

multilang-documentation


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 multilang-documentation/canonical.lisp

Dependency

package.lisp (file)

Parent

multilang-documentation (system)

Location

canonical.lisp

Exported Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 multilang-documentation/language.lisp

Dependency

canonical.lisp (file)

Parent

multilang-documentation (system)

Location

language.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.5 multilang-documentation/drop-in.lisp

Dependency

language.lisp (file)

Parent

multilang-documentation (system)

Location

drop-in.lisp

Exported Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.6 multilang-documentation/documentation.lisp

Dependency

drop-in.lisp (file)

Parent

multilang-documentation (system)

Location

documentation.lisp


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 multilang-documentation

Source

package.lisp (file)

Nickname

org.shirakumo.multilang-documentation

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 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 (file)

Writer

(setf documentation) (function)

Function: (setf documentation) DOCSTRING OBJECT TYPE &key LANG
Package

multilang-documentation

Source

drop-in.lisp (file)

Reader

documentation (function)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

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 (file)

Writer

(setf documentation*) (generic function)

Methods
Method: documentation* OBJECT TYPE IDENTIFIER
Method: documentation* OBJECT TYPE (LANGUAGE language)
Generic Function: (setf documentation*) DOCSTRING OBJECT TYPE LANGUAGE
Package

multilang-documentation

Reader

documentation* (generic function)

Methods
Method: (setf documentation*) DOCSTRING OBJECT TYPE IDENTIFIER
Source

drop-in.lisp (file)

Method: (setf documentation*) DOCSTRING OBJECT TYPE (LANGUAGE language)
Source

drop-in.lisp (file)

Generic Function: 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 (file)

Methods
Method: documentation-storage (SIMPLE-LANGUAGE simple-language)

automatically generated reader method

Generic Function: identifier LANGUAGE

Returns the identifier of the object.

See NO-SUCH-LANGUAGE
See SIMPLE-LANGUAGE

Package

multilang-documentation

Source

language.lisp (file)

Methods
Method: identifier (SIMPLE-LANGUAGE simple-language)

automatically generated reader method

Method: identifier (CONDITION no-such-language)
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 (file)

Writer

(setf language) (generic function)

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) LANGUAGE IDENTIFIER
Package

multilang-documentation

Reader

language (generic function)

Methods
Method: (setf language) LANGUAGE (IDENTIFIER symbol)
Source

language.lisp (file)

Method: (setf language) (LANGUAGE language) (IDENTIFIER string)
Source

language.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Conditions

Condition: no-such-language ()

Error signalled when an inexistent language is referenced.

See IDENTIFIER
See LANGUAGE

Package

multilang-documentation

Source

language.lisp (file)

Direct superclasses

error (condition)

Direct methods

identifier (method)

Direct slots
Slot: identifier
Initargs

:identifier

Readers

identifier (generic function)


Previous: , Up: Exported definitions   [Contents][Index]

5.1.5 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 (file)

Direct superclasses

standard-object (class)

Direct subclasses

simple-language (class)

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 (file)

Direct superclasses

language (class)

Direct methods
Direct slots
Slot: %identifier
Initargs

:identifier

Readers

identifier (generic function)

Slot: %documentation-storage
Initform

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

Readers

documentation-storage (generic function)

Direct Default Initargs
InitargValue
:identifier(error "identifier required.")

Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

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 (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 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 (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   M  
Index Entry  Section

F
File, Lisp, multilang-documentation.asd: The multilang-documentation<dot>asd file
File, Lisp, multilang-documentation/canonical.lisp: The multilang-documentation/canonical<dot>lisp file
File, Lisp, multilang-documentation/documentation.lisp: The multilang-documentation/documentation<dot>lisp file
File, Lisp, multilang-documentation/drop-in.lisp: The multilang-documentation/drop-in<dot>lisp file
File, Lisp, multilang-documentation/language.lisp: The multilang-documentation/language<dot>lisp file
File, Lisp, multilang-documentation/package.lisp: The multilang-documentation/package<dot>lisp file

L
Lisp File, multilang-documentation.asd: The multilang-documentation<dot>asd file
Lisp File, multilang-documentation/canonical.lisp: The multilang-documentation/canonical<dot>lisp file
Lisp File, multilang-documentation/documentation.lisp: The multilang-documentation/documentation<dot>lisp file
Lisp File, multilang-documentation/drop-in.lisp: The multilang-documentation/drop-in<dot>lisp file
Lisp File, multilang-documentation/language.lisp: The multilang-documentation/language<dot>lisp file
Lisp File, multilang-documentation/package.lisp: The multilang-documentation/package<dot>lisp file

M
multilang-documentation.asd: The multilang-documentation<dot>asd file
multilang-documentation/canonical.lisp: The multilang-documentation/canonical<dot>lisp file
multilang-documentation/documentation.lisp: The multilang-documentation/documentation<dot>lisp file
multilang-documentation/drop-in.lisp: The multilang-documentation/drop-in<dot>lisp file
multilang-documentation/language.lisp: The multilang-documentation/language<dot>lisp file
multilang-documentation/package.lisp: The multilang-documentation/package<dot>lisp file

Jump to:   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

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

(
(setf documentation): Exported functions
(setf documentation*): Exported generic functions
(setf documentation*): Exported generic functions
(setf documentation*): Exported generic functions
(setf language): Exported generic functions
(setf language): Exported generic functions
(setf language): Exported generic functions

C
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions
canonicalize-doctype: Exported generic functions

D
documentation: Exported functions
documentation*: Exported generic functions
documentation*: Exported generic functions
documentation*: Exported generic functions
documentation-storage: Exported generic functions
documentation-storage: Exported generic functions

F
Function, (setf documentation): Exported functions
Function, documentation: Exported functions
Function, prompt-language: Internal functions

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

I
identifier: Exported generic functions
identifier: Exported generic functions
identifier: Exported generic functions

L
language: Exported generic functions
language: Exported generic functions
language: Exported generic functions
language: Exported generic functions

M
Method, (setf documentation*): Exported generic functions
Method, (setf documentation*): Exported generic functions
Method, (setf language): Exported generic functions
Method, (setf language): Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, canonicalize-doctype: Exported generic functions
Method, documentation*: Exported generic functions
Method, documentation*: Exported generic functions
Method, documentation-storage: Exported generic functions
Method, identifier: Exported generic functions
Method, identifier: Exported generic functions
Method, language: Exported generic functions
Method, language: Exported generic functions
Method, language: Exported generic functions

P
prompt-language: Internal functions

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

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   %   *  
I   S  
Index Entry  Section

%
%documentation-storage: Exported classes
%identifier: Exported classes

*
*language*: Exported special variables
*languages*: Internal special variables

I
identifier: Exported conditions

S
Slot, %documentation-storage: Exported classes
Slot, %identifier: Exported classes
Slot, identifier: Exported conditions
Special Variable, *language*: Exported special variables
Special Variable, *languages*: Internal special variables

Jump to:   %   *  
I   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

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

C
Class, language: Exported classes
Class, simple-language: Exported classes
Condition, no-such-language: Exported conditions

L
language: Exported classes

M
multilang-documentation: The multilang-documentation system
multilang-documentation: The multilang-documentation package

N
no-such-language: Exported conditions

P
Package, multilang-documentation: The multilang-documentation package

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

Jump to:   C   L   M   N   P   S