multilang documentation

Table of Contents

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.

System Information

Definition Index

• MULTILANG-DOCUMENTATION

  • ORG.SHIRAKUMO.MULTILANG-DOCUMENTATION

  No documentation provided.

  • EXTERNAL SPECIAL-VARIABLE

    *LANGUAGE*

    Source

    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

  • EXTERNAL CLASS

    LANGUAGE

    Source

    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*

  • EXTERNAL CLASS

    SIMPLE-LANGUAGE

    Source

    A simple language object that keeps its identifier and a docstring storage.
    
    See LANGUAGE
    See IDENTIFIER
    See DOCUMENTATION-STORAGE
    See LANGUAGE

  • EXTERNAL CONDITION

    NO-SUCH-LANGUAGE

    Source

    Error signalled when an inexistent language is referenced.
    
    See IDENTIFIER
    See LANGUAGE

  • EXTERNAL FUNCTION

    DOCUMENTATION

    • OBJECT
    • TYPE
    • &KEY
    • LANG
    • &REST

    Source

    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*

  • EXTERNAL FUNCTION

    (SETF DOCUMENTATION)

    • DOCSTRING
    • OBJECT
    • TYPE
    • &KEY
    • LANG
    • &REST

    Source

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    CANONICALIZE-DOCTYPE

    • OBJECT
    • TYPE
    • &REST

    Source

    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

  • EXTERNAL GENERIC-FUNCTION

    DOCUMENTATION*

    • OBJECT
    • TYPE
    • LANG
    • &REST

    Source

    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

  • EXTERNAL GENERIC-FUNCTION

    (SETF DOCUMENTATION*)

    • DOCSTRING
    • OBJECT
    • TYPE
    • LANGUAGE
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    DOCUMENTATION-STORAGE

    • LANGUAGE
    • &REST

    Source

    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*

  • EXTERNAL GENERIC-FUNCTION

    IDENTIFIER

    • LANGUAGE
    • &REST

    Source

    Returns the identifier of the object.
    
    See NO-SUCH-LANGUAGE
    See SIMPLE-LANGUAGE

  • EXTERNAL GENERIC-FUNCTION

    LANGUAGE

    • IDENTIFIER
    • &KEY
    • IF-DOES-NOT-EXIST
    • &REST

    Source

    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

  • EXTERNAL GENERIC-FUNCTION

    (SETF LANGUAGE)

    • LANGUAGE
    • IDENTIFIER
    • &REST

    No documentation provided.