Skip to content
Snippets Groups Projects

Compare revisions

Changes are shown as if the source revision was being merged into the target revision. Learn more about comparing revisions.

Source

Select target project
No results found

Target

Select target project
  • rae/haddock
  • sjakobi/haddock
  • RyanGlScott/haddock
  • mynguyenbmc/haddock
  • kcsongor/haddock
  • wz1000/haddock
  • dten/haddock
  • bgamari/haddock
  • abrar/haddock
  • obsidiansystems/haddock
  • inaki/haddock
  • hsyl20/haddock
  • JoshMeredith/haddock
  • matheus23/haddock
  • Gertjan423/haddock
  • ulysses4ever/haddock
  • facundominguez/haddock
  • SuedeHead/haddock
  • Haskell-mouse/haddock
  • fgaz/haddock
  • arybczak/haddock
  • coot/haddock
  • hithroc/haddock
  • ani/haddock
  • supersven/haddock
  • alt-romes/haddock
  • sspencer/haddock
  • Joald/haddock
  • raehik/haddock
  • lexi.lambda/haddock
  • torsten.schmits/haddock
  • Bodigrim/haddock
  • doyougnu/haddock
  • barci2/haddock
  • Jade/haddock
  • wavewave/haddock
  • soulomoon/haddock
  • tvh/haddock
  • trac-sjoerd_visscher/haddock
  • Kleidukos/haddock
  • mmzk1526/haddock
  • stephenjudkins/haddock
  • KommuSoft1/haddock
43 results
Show changes
Commits on Source (3789)
3,689 additional commits have been omitted to prevent performance issues.
Hide whitespace changes
Inline Side-by-side
Showing
with 1783 additions and 191 deletions
.github/mergify.yml 0 → 100644
View file @ c9bc29c6
pull_request_rules:
# rebase+merge strategy
- actions:
queue:
name: default
# Merge into master with a merge commit
method: merge
# Update the pr branch with rebase, so the history is clean
update_method: rebase
name: Put pull requests in the rebase+merge queue
conditions:
- label=merge me
- '#approved-reviews-by>=1'
# merge+squash strategy
- actions:
queue:
name: default
method: squash
# both update methods get absorbed by the squash, so we use the most
# reliable
update_method: merge
name: Put pull requests in the squash+merge queue
conditions:
- label=squash+merge me
- '#approved-reviews-by>=1'
queue_rules:
- name: default
conditions: []
.github/workflows/ci.yml 0 → 100644
View file @ c9bc29c6
name: CI
# Trigger the workflow on push or pull request, but only for the master branch
on:
pull_request:
push:
branches: ["ghc-head"]
jobs:
cabal:
name: ${{ matrix.os }} / ghc ${{ matrix.ghc }}
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest]
cabal: ["3.6"]
ghc:
- "head"
steps:
- uses: actions/checkout@v2
if: github.event.action == 'opened' || github.event.action == 'synchronize' || github.event.ref == 'refs/heads/ghc-head'
- name: Install gmp and tinfo
run: |
sudo -- sh -c "apt-get update"
sudo -- sh -c "apt-get -y install libgmp-dev libtinfo-dev"
- uses: haskell/actions/setup@main
id: setup-haskell-cabal
name: Setup Haskell
with:
ghc-version: ${{ matrix.ghc }}
cabal-version: ${{ matrix.cabal }}
- name: Prepare environment
run: echo "$HOME/.ghcup/bin" >> $GITHUB_PATH
- name: Freeze
run: |
cabal freeze
- uses: actions/cache@v2
name: Cache ~/.cabal/store
with:
path: |
${{ steps.setup-haskell-cabal.outputs.cabal-store }}
key: ${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('cabal.project.freeze') }}
- name: Build
run: |
cabal configure --enable-tests --enable-benchmarks --test-show-details=direct
cabal build all
- name: Test
run: cabal test --test-show-details=direct --test-options="--haddock-stdout=/dev/stdout" all
.github/workflows/hlint-ci.yml 0 → 100644
View file @ c9bc29c6
name: hlint
on:
pull_request:
push:
jobs:
build:
name: hlint
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
with:
submodules: true
- uses: rwe/actions-hlint-setup@v1
name: Set up HLint
with:
version: "3.4.1"
- uses: rwe/actions-hlint-run@v2
name: hlint
with:
path: '[ "haddock-library/", "haddock-api/", "haddock-test/", "hoogle-test/", "html-test/", "hypsrc-test/", "latex-test/" ]'
fail-on: suggestion
\ No newline at end of file
.gitignore 0 → 100644
View file @ c9bc29c6
/dist/
/dist-newstyle/
/haddock-api/dist/
/haddock-library/dist/
/haddock-test/dist/
/html-test/out/
/hypsrc-test/out/
/latex-test/out/
/hoogle-test/out/
*.o
*.hi
*.dyn_o
*.dyn_hi
*.hp
/doc/haddock
/doc/haddock.ps
/doc/haddock.pdf
/doc/autom4te.cache/
/doc/config.log
/doc/config.mk
/doc/config.status
/doc/configure
tags
TAGS
/haddock-api/resources/html/node_modules
/haddock-api/resources/html/*.js.map
.cabal-sandbox
.ghc.environment.*
cabal.sandbox.config
cabal.project.local
cabal.project.local~
.stack-work/
.hspec-failures
.hlint.yaml 0 → 100644
View file @ c9bc29c6
# Warnings currently triggered
- ignore: {name: "Avoid lambda"} # 3 hints
- ignore: {name: "Avoid lambda using `infix`"} # 5 hints
- ignore: {name: "Eta reduce"} # 18 hints
- ignore: {name: "Functor law"} # 3 hints
- ignore: {name: "Fuse concatMap/map"} # 1 hint
- ignore: {name: "Fuse foldr/map"} # 2 hints
- ignore: {name: "Fuse mapM/map"} # 2 hints
- ignore: {name: "Hoist not"} # 1 hint
- ignore: {name: "Move brackets to avoid $"} # 7 hints
- ignore: {name: "Move guards forward"} # 1 hint
- ignore: {name: "Move map inside list comprehension"} # 2 hints
- ignore: {name: "Redundant <$>"} # 3 hints
- ignore: {name: "Redundant bracket"} # 44 hints
- ignore: {name: "Redundant id"} # 1 hint
- ignore: {name: "Redundant if"} # 3 hints
- ignore: {name: "Redundant lambda"} # 2 hints
- ignore: {name: "Redundant map"} # 3 hints
- ignore: {name: "Redundant return"} # 1 hint
- ignore: {name: "Replace case with fromMaybe"} # 2 hints
- ignore: {name: "Replace case with maybe"} # 4 hints
- ignore: {name: "Use $>"} # 4 hints
- ignore: {name: "Use ++"} # 3 hints
- ignore: {name: "Use :"} # 4 hints
- ignore: {name: "Use <$>"} # 12 hints
- ignore: {name: "Use <&>"} # 1 hint
- ignore: {name: "Use <|>"} # 1 hint
- ignore: {name: "Use =<<"} # 1 hint
- ignore: {name: "Use all"} # 1 hint
- ignore: {name: "Use bimap"} # 1 hint
- ignore: {name: "Use camelCase"} # 31 hints
- ignore: {name: "Use concatMap"} # 1 hint
- ignore: {name: "Use const"} # 4 hints
- ignore: {name: "Use fewer LANGUAGE pragmas"} # 1 hint
- ignore: {name: "Use find"} # 1 hint
- ignore: {name: "Use fmap"} # 12 hints
- ignore: {name: "Use foldr"} # 1 hint
- ignore: {name: "Use fromMaybe"} # 2 hints
- ignore: {name: "Use infix"} # 3 hints
- ignore: {name: "Use intercalate"} # 1 hint
- ignore: {name: "Use isAsciiLower"} # 1 hint
- ignore: {name: "Use isAsciiUpper"} # 1 hint
- ignore: {name: "Use isDigit"} # 1 hint
- ignore: {name: "Use lambda-case"} # 4 hints
- ignore: {name: "Use let"} # 2 hints
- ignore: {name: "Use list comprehension"} # 2 hints
- ignore: {name: "Use list literal pattern"} # 1 hint
- ignore: {name: "Use map once"} # 1 hint
- ignore: {name: "Use maybe"} # 2 hints
- ignore: {name: "Use newtype instead of data"} # 13 hints
- ignore: {name: "Use notElem"} # 2 hints
- ignore: {name: "Use print"} # 3 hints
- ignore: {name: "Use record patterns"} # 5 hints
- ignore: {name: "Use second"} # 3 hints
- ignore: {name: "Use sortOn"} # 3 hints
- ignore: {name: "Use tuple-section"} # 3 hints
- ignore: {name: "Use unless"} # 1 hint
- ignore: {name: "Use void"} # 1 hint
# Ignore within modules where following hlint or adding an HLint annotation
# would alter the expected test output.
- ignore: {name: "Unused LANGUAGE pragma", within: [QuasiExpr, TH, Ticket112]}
# Module names (not all unique) where CPP can be used
- extensions:
- name: CPP
within:
- Bug1091
- CompatPrelude
- CPP
- Documentation.Haddock.Parser.UtilSpec
- Documentation.Haddock.Types
- Haddock
- Haddock.Config
- Haddock.Convert
- Haddock.Interface
- Haddock.Interface.Create
- Haddock.InterfaceFile
- Haddock.Types
- Haddock.Utils
- Haddock.Version
- Haddock.Backends.Xhtml
- Main
- Test.Haddock.Config
CHANGES deleted 100644 → 0
View file @ 1c0a3bed
Changes in version 0.3:
* Documentation on individual function arguments is now implemented
* Links can be made to identifiers that aren't in scope, by using
the fully qualified name.
* Instances are collected and listed with the appropriate classes
and datatypes (not for derived instances yet).
* Single quotes are only interpreted specially when they surround a
legal Haskell identifier, otherwise they are treated literally.
* Bird-tracked text is now literal. If you want marked-up text in
a code block, use the @...@ notation instead.
* Various changes to the layout, it generally looks nice now.
* Various bugs fixed.
-----------------------------------------------------------------------------
Changes in version 0.2:
* The [...] markup for typewriter font has been changed to @...@.
* Module attributes introduced (see the documentation for details).
* {- ... -} style comments may now be used for documentation annotations
* Recursive modules are detected and reported as an error.
* Existential constructors and rank-N types are now groked by the parser
* Some type rendering cleaned up
* `abc' is accepted as well as 'abc' to markup an identifier
* Several bugs fixed, and error messages improved.
CHANGES.md 0 → 100644
View file @ c9bc29c6
## Changes in 2.28.0
* `hi-haddock` is integrated, which means docstrings are no longer extracted
through typchecked module results. Instead, docstrings are taken from Haskell
interface (`.hi`) files.
* Support qualified and unqualified names in `--ignore-link-symbol`.
* Add `--trace-args` flag which prints arguments to standard output. This is
useful for examining arguments passed when Haddock is invoked through `cabal
haddock`, as `cabal` uses temporary response files to pass arguments to
Haddock.
* Avoid recompilation due to changes in optimization flags.
## Changes in 2.24.0
* Reify oversaturated data family instances correctly (#1103)
* Removed the majority of Haddock's possible `panic` routes through
the TTG refactor to make extension variants empty
## Changes in 2.23.0
* "Linuwial" is the new default theme (#721, #782, #949)
* Fix style switcher (enabled by `--built-in-themes`) (#949)
* Support inline markup in markdown-style links (#875)
* The hyperlinker backend has been re-engineered to use HIE files
and display type annotations on expressions (#977)
* The hyperlinker backend lexer is now more incremental, faster, and
more memory efficient (#977)
* Add an "Instances" menu item to the HTML backend for controlling
settings related to expanding/collapsing instances (#1007)
* Improved identifier links including value/type namespaces, and
hyperlinking of parenthesized/backticked identifiers
* Substantial bugfixes for converting `TyThing` back into source
declarations (#1003, #1005, #1022, #1020)
* `--show-interface` now outputs to stdout (instead of stderr)
* Render associated type defaults and also improve rendering of
default method signatures
* Many fixes to the LaTeX backend, mostly focused on not crashing
as well as generating LaTeX source that compiles
* More flexible parsing of the module header
## Changes in version 2.22.0
* Make `--package-version` optional for `--hoogle` (#899)
* Support type and data families in the LaTeX backend (#734)
* Support pattern synonyms in the Hoogle backend (#947)
## Changes in version 2.21.0
* Overhaul handling of data declarations in XHTML and LaTeX. Adds support for
documenting individual arguments of constructors/patterns (#709)
* Actually list all fixities for `--hoogle` (#871)
* Fix broken instance source links (#869)
* Avoiding line breaks due to ling line in the output of `--hoogle` (#868)
* Capture docs on type family instances (#867)
## Changes in version 2.20.0
* Show where instances are defined (#748)
* `@since` includes package name (#452, #550, #749)
## Changes in version 2.19.0.1
* Support for linking unicode operators (#458)
* Hyperlinker: Fix file handle leak in (#763)
## Changes in version 2.19.0
* Haddock now supports tables in documentation inspired by reSTs grid tables
* `--quickjump` allows for quick navigation in documentation on hackage and
other documentation hosting sites.
* A --reexport flag, which can be used to add extra modules to the
top-level module tree
* Haddock no longer reports coverage statistics for hidden modules. By default
cabal-install marks all package internal modules as hidden.
* Haddock now writes additional information about the documentation to `meta.json`
* Fix renaming of type variables after specializing instance method signatures (#613)
* Move markup related data types to haddock-library
* Fix: Show empty constraint contexts in pattern type signatures (#663)
* Fix: Generate constraint signatures for constructors exported as pattern
synonyms (#663)
* The hyperlinker backend now uses the GHC lexer instead of a custom one.
This notably fixes rendering of quasiquotes.
* Overhaul Haddock's rendering of kind signatures so that invisible kind
parameters are not printed (#681) (Fixes #544)
* Recognise `SPDX-License-Identifier` as alias for `License` in module header
parser (#743)
* Remove the response file related utilities, and use the ones that
come with `base` (Trac #13896)
* Remove the response file related utilities, and use the ones that
come with `base` (Trac #13896)
## Changes in version 2.18.1
* Synopsis is working again (#599)
* Per-argument documentation on class methods working again (#647)
* Support user defined signatures on pattern synonyms
* Support for bundled pattern synonyms (#494, #551, #626)
## Changes in version 2.17.4
* Fix 'internal error: links: UnhelpfulSpan' (#554, #565)
* Hyperlink backend knows about `DataKinds` (#510)
* Fix rendering of class methods for `Eq` and `Ord` (#549)
* Export `MDoc` and `toInstalledIface` from `Haddock.Types`
## Changes in version 2.17.3.1
* Disable `NFData` instances for GHC types when GHC >= 8.0.2 (#537)
## Changes in version 2.17.3
* Remove framed view of the HTML documentation
## Changes in version 2.17.2
* Fix portability of documentation building within GHC
## Changes in version 2.17.1
* Included with GHC 8.0.1
* Fixed Makefile for GHC installation
* Fixed clean rule of GHC Makefile
## Changes in version 2.17.0 (not released)
* Support typesetting of mathematical expressions via Mathjax (#397)
* Describe orphan instances defined in a module in its documentation (#449)
* Produce specialized type signatures for typeclass methods (#425)
* Support GCC-like response files (#470)
## Changes in version 2.16.2
* Generate hyperlinked source ourselves (#410, part of GSOC 2015)
* Fix expansion icon for user-collapsible sections (#412)
* Break up response file arguments on newlines
* Various HTML fixes (#301, #406, #407, #421)
* Line anchors in hyperlinked source (#420)
## Changes in version 2.16.1
* Don't default to type constructors for out-of-scope names (#253 and
#375)
* Fix Hoogle display of constructors (#361)
* Fully qualify names in Hoogle instances output (#263)
* Output method documentation in Hoogle backend (#259)
* Don't print instance safety information in Hoogle (#168)
* Expand response files in arguments (#285)
* Build the main executable with -threaded (#399)
* Use SrcSpan of declarations for inferred type sigs (#207)
* Fix cross-module instance locations (#383)
* Fix alignment of Source link for instances in Firefox (#384)
## Changes in version 2.16.0
* Experimental collapsible header support (#335)
* Add support for markdown links and images
* Allow an optional colon after the closing bracket of definition lists.
This is to disambiguate them from markdown links and will be require with a
future release.
* Fix re-exports of built-in type families (#310)
* Fix parsing of infix identifiers such as ``elem``.
* Print missing docs by default and add --no-print-missing-docs
* parser: now parses out some meta data too, breaking the API
* parser: markdown syntax for images and URLs is now accepted:
<<foo>> style for images and <foo bar> style for links is now
considered deprecated. <foo> for links is still OK.
* parser: add support for @since element: this is paragraph-level
element of the form ‘@since x.y.z’ where x.y.z is the version
number. The way it is rendered is subject to change.
* properly render package ID (not package key) in index (#329)
* links to source location of class instance definitions
* Fix code blocks in presence of Windows line endings
* Deal better with long synopsis lines (#151)
## Changes in version 2.15.0
* Always read in prologue files as UTF8 (#286 and Cabal #1721)
* parser: don't wrap headers in DocParagraph (#307)
* parser: don't mangle append order for nested lists (pandoc #1346)
* parser: preserve list ordering in certain scenarios (#313)
* parser: update the attoparsec version used internally giving slight
parsing performance boost.
* Move development to be against latest GHC release and not GHC HEAD.
* Further split up the package to separate the executable from the
library, necessary by things like GHCJS. We now have
‘haddock-library’ which are the parts that don't use GHC API,
‘haddock-api’ which are (some of) the parts that do use GHC API and
‘haddock’ which merely provides the executable.
* Export few extra functions in the API.
* Add compatibility with GHC 7.8.2.
* Omit unnecessary ‘forall’s (#315 and #86)
* Remove some files which were really old or did not belong in the
repository in the first place.
## Changes in version 2.14.3
* Fix parsing of identifiers with ^ or ⋆ in them (#298)
* Fix anchors (#308)
## Changes in version 2.14.2
* Always drop --split-objs GHC flag for performance reasons (#292)
* Print kind signatures GADTs (#85)
* Drop single leading whitespace when reasonable from @-style blocks (#201)
* Fix crashes associated with exporting data family record selectors (#294)
## Changes in version 2.14.1
* Render * and -> with their UnicodeSyntax equivalents if -U is enabled
* Display minimal complete definitions for type classes
* Hide right hand side of TF instances with hidden names on the RHS
## Changes in version 2.14.0
* Print entities with missing documentation (#258)
* Print a warning message when given `-optghc` instead of `--optghc` (#5)
* Add `--compatible-interface-versions` (#231)
* Allow to generate latex documentation for FFI declarations (#247)
* Add copyright and license information to generated documentation
* Improved to Unicode support
* Bold markup support
* Nested paragraphs
* Better escaping
* Header markup
* Parser should no longer fail to parse any markup
* {-# OPTIONS_HADDOCK show-extensions #-} pragma will show the GHC extensions
enabled in the module.
* Properly render License field (#271)
* Print type/data family instances (for exported types only)
* Fix display of poly-kinded type operators (#189)
* PatternSynonyms support
* Fix display of implicit parameters (#260)
* Fix rendering of Contents when links are present (#276)
* Fix documentation duplication on record fields (#195)
* Add `--source-entity-line` for exact line links (eg. things defined
inside TH splices) (#79)
* Display fixity information for names with nonstandard fixities
* Bird tracks specified like "> code" no longer suffer from an extra leading
space in the code output
## Changes in version 2.13.2
* Handle HsExplicitListTy in renamer (#213)
* Allow haddock markup in deprecation messages
* Export more types from Documentation.Haddock
* Include everything that is required to run the test suite with the cabal
package (#230)
## Changes in version 2.13.1
* Hide instances that are "internal" to a module
* Add support for properties in documentation
* Fix a bug with spurious superclass constraints
* Fix and extend the Haddock API
## Changes in version 2.12.0
* Labeled URLs (e.g <http://example.net/ some label>)
* Improved memory usage (new dependency: deepseq)
## Changes in version 2.11.0
* Show deprecation messages for identifiers
* List identifiers declared on the same line (with a common type) separately
* Don't crash on unicode strings in doc comments
* Fix reporting of modules safe haskell mode
* Fix a case where we were generating invalid xhtml
* Improved --qual option (no crashes, proper error messages)
* A new --qual option "aliased" which qualifies identifiers by the module alias
used in the source code
* The Haddock API restores GHC's static flags after invocation
* Access to unexported identifiers through the Haddock API again
## Changes in version 2.10.0
* Require GHC >= 7.4
* Safe Haskell indications on module pages
* Type declarations on identifiers no longer necessary
* Add flag --interface-version
* Warn when comment refers to in-scope identifier without documentation
* Bug fix: links to out-of-scope things (#78)
* Bug fix: module references to other packages work again
## Changes in version 2.9.4
* Require GHC >= 7.2
* Support Alex 3.x
## Changes in version 2.9.3
[This is the version that comes with GHC 7.2.1 although it claims it's 2.9.2!]
* Build with GHC 7.2.1
* Support blank lines in results of examples
* A type signature for multiple names generates one signature in the output
* Minor bug fixes
## Changes in version 2.9.2
* Build with GHC 7.0.2
* Write Hoogle output in utf8; fixes GHC build on Windows
## Changes in version 2.9.1
* Fix build in GHC tree
* Improve .cabal file
## Changes in version 2.9.0
* Drop support for ghc < 7
* New flag --qual for qualification of names
* Print doc coverage information to stdout when generating docs
* Include an 'All' option in the A-Z subdivided index
* Make TOC group header identifiers validate
* Minor changes to the API
## Changes in the version that comes with GHC 7.0.1
[This version claims it is 2.8.0 but is actually based on 2.8.1]
* Fix URL creation on Windows: Use / not \ in URLs.
* Support GHC 7.0
## Changes in version 2.8.1
* Fix build on Windows with MinGW
## Changes in version 2.8.0
* HTML backend completely rewritten to generate semantically rich XHTML
using the xhtml package.
* New default CSS based on the color scheme chosen for the new Haskell
wiki, with a pull-out tab for the synopsis.
* Theme engine based on CSS files. Themes can be switched from the
header menu. (New flags --built-in-themes and --theme. The latter
is an alias for --css which now has extended semantics).
* Markup support for executable examples/unit-tests. To be used with an
upcoming version of the DocTest program.
* Addition of a LaTeX backend.
* Frames-mode can be enabled from the header menu.
* Path to source entities can be specified per package, so that source
links work for cross-package documentation.
* Support for a second form of enumerated lists (1. 2. etc).
* Additions and changes to the Haddock API.
* New flag --no-tmp-comp-dir to tell Haddock to write and pick up
compilation files (.o, .hi, etc) to/from GHC's output directory instead
of a temporary directory.
* Various bug fixes.
-----------------------------------------------------------------------------
## Changes in version 2.6.1 (bug fix release from the stable branch)
* Fix #128
-----------------------------------------------------------------------------
## Changes in version 2.7.2
* Add Paths_haddock to library
-----------------------------------------------------------------------------
## Changes in version 2.7.1:
* Fix problems with library part of .cabal file
-----------------------------------------------------------------------------
## Changes in version 2.7.0:
* Instances can be commented
* The Haddock API now exposes more of the internals of Haddock
* Bug fixes (most importantly #128)
-----------------------------------------------------------------------------
## Changes in version 2.6.0:
* Drop support for GHC 6.10.*
* Add support for GHC 6.12.1
* Cross-package documentation: full documentation show up when re-exporting
things coming from external packages
* Lexing and parsing the Haddock comment markup is now done in Haddock
again, instead of in GHC
* Slightly prettier printing of instance heads
* Support platforms for which GHC has no native code generator
* Add a flag --print-ghc-libdir
* Minor bug fixes
-----------------------------------------------------------------------------
Changed in version 2.5.0:
* Drop support for GHC 6.8.*
* Add support for GHC 6.10.3 and 6.10.4
* Revert to the old multi-page index for large packages (#106)
* Show GADT records in the generated documentation
* Create output directory if it doesn't exist (#104)
* Use the native codegen instead of compiling via C for TH modules
* Add --use-unicode flag for displaying prettier versions of common symbols
* Multiple verbosity levels: remove --verbose and add --verbosity=n
-----------------------------------------------------------------------------
Changed in version 2.4.2:
* Support GHC 6.10.2
* Haddock no longer crashes on Template Haskell modules (#68)
(only with GHC 6.10.2 or above)
* Fix problem with Template Haskell-generated declarations disappearing (#59)
* Generate two anchors for each link for compatibility between IE and Opera
(#45)
* Improved error messages
* Show re-exports from external packages again (GHC ticket #2746)
* Store hidden modules in .haddock files again (needed by the haddock
library)
* Avoid processing boot modules
* Pragmas may exist between document comments and declarations
* Do not indicate that a constructor argument is unboxed
* Fix problem with non-working links to ghc-prim
* Allow referring to a specific section within a module in a module link
(#65)
* Fixes to the Hoogle backend
* Improvements to the haddock library
* Many other fixes (including #67, #69, #58, #57)
-----------------------------------------------------------------------------
Changed in version 2.4.1:
* Depend on base 4.* when GHC >= 6.9, otherwise 3.*
-----------------------------------------------------------------------------
Changed in version 2.4.0:
* Add framed view of the HTML documentation
* Build with GHC 6.8.2 and 6.8.3 again
* Support images in documentation comments again
* Small improvements to the Hoogle output
* A few bugs has been fixed
-----------------------------------------------------------------------------
Changed in version 2.3.0:
* Support for GHC 6.10.1
* Slightly improved space usage
* Fix a bug that made hidden modules show up in the contents & index pages
* Fix a bug that made Haddock load modules twice
* Improvements to the Hoogle output
-----------------------------------------------------------------------------
Changed in version 2.2.2:
* Relax version dependency on ghc-paths
-----------------------------------------------------------------------------
## Changes in version 2.2.1:
* Support for GHC 6.8.3
* The Hoogle backend is back, thanks to Neil Mitchell. The plan is to be
compatible with the upcoming Hoogle 4 pre-release
* Show associated types in the documentation for class declarations
* Show type family declarations
* Show type equality predicates
* Major bug fixes (#1 and #44)
* It is no longer required to specify the path to GHC's lib dir
* Remove unnecessary parenthesis in type signatures
-----------------------------------------------------------------------------
## Changes in version 2.1.0:
* Fix a bug that made links point to the defining module instead
of the "best" one (e.g Int pointing to GHC.Base instead of Data.Int)
* Fix a couple of smaller bugs
* The representation of DocName was changed in the library
* Add a flag --no-warnings for turning off warnings
-----------------------------------------------------------------------------
## Changes in version 2.0.0.0:
* The GHC API is used as the front-end
* Haddock now understands all syntax understood by GHC 6.8.2
* Haddock can generate documentation for some of the language extensions
in GHC 6.8.2
* Format of module attributes has changed. The only way of specifying
module attributes is via a new OPTIONS_HADDOCK pragma. Example:
{-# OPTIONS_HADDOCK hide, prune #-}
* Haddock understands literate source files
* Add a small library to read Haddock's interface files
* Add a flag -B for passing the path to the GHC lib dir
* Add a flag --optghc for passing options to GHC
* Add a flag --ghc-version for printing the GHC version
* Remove --use-package, --allow-missing-html, --ghc-pkg, in favour of only
supporting --read-interface
* Remove --package flag, the GHC flag -package-name can be used instead
* Remove --no-implicit-prelude flag, the GHC flag -XNoImplicitPrelude can
be used instead
-----------------------------------------------------------------------------
## Changes in version 0.9:
* Infix type operators, e.g., first :: a~>a' -> (a,b)~>(a',b)
* Add a search box to the index page which automatically narrows
the index to the search as you type (thanks to Neil Mitchell).
* Add a --ghc-pkg flag
* Add a flag --allow-missing-html
* URL expansion for %%, %L, %{LINE}
* added substitution %{FILE///c}
* Lexing of /.../ is now more like '...', in that a / character must
be matched by another / character on the same line, otherwise it
is treated as a literal '/'. This removes a common source of
accidental parse errors in documentation.
* Various bugs were fixed.
* Cabal 1.2 is now required, and Haddock builds with GHC 6.8.x.
-----------------------------------------------------------------------------
## Changes in version 0.8:
* Haddock has a Cabal build system, and will build on Windows without
Cygwin or MSYS. GHC 6.4 or later is required.
* New options: --comments-base, --comments-module, --comments-entity
for generating links to pages (eg. wiki) for collecting user comments.
* New options: --source-base, --source-module, --source-entity
for generating links to source code. Haddock now understands
{-# LINE #-} pragmas, which means it can figure out the correct
name for the source file even if the file is preprocessed.
* Haddock generates output for populating the Hoogle search engine.
* New markup <<url>> for including images.
-----------------------------------------------------------------------------
## Changes in version 0.7:
* ## Changes in the way Haddock decides where to direct hyperlinks. Each entity
is now assigned a single "home" module, and all hyperlinks are directed
to that module. See the docs ("Hyperlinking and re-exported entities")
for details.
* New options --ignore-all-exports, --hide
* New option --use-package for creating documentation that hyperlinks to
the HTML documentation for existing packages on your system. It works
by querying ghc-pkg for the location of the Haddock interface and
HTML for the given package.
* Parts of the HTML documentation, notably lists of instances, are
now "collapsible" with a +/- button. Also, the contents page is now
in the form of tree in which subtrees can be collapsed.
* Support for Microsoft DevHelp and HtmlHelp 2.0 formats.
* Support for a short description for each module for the contents page.
* Compiles with GHC 6.4+
* Various bugfixes
-----------------------------------------------------------------------------
## Changes in version 0.6:
* Implicit parameters, zip comprehensions and 'mdo' are now
supported by the parser.
* Some lexical bugs were fixed, mainly concerning literal paragraphs
next to non-literal paragraphs.
* New options: --gen-index, --use-index, --gen-contents and --use-contents,
for generting a combined index and contents for several libraries
from the appropriate .haddock files.
* There is now one index rather than separate Function/Constructor and
Type/Class indices. Where a name refers to several entities, these
are listed separately in the index.
* New option: -v, elicits more verbose warnings. Some warnings are
now turned off by default; Haddock should be a little less noisy
in general.
* Markup for definition lists has been added. See the documentation
for details.
* New option: --package for setting the package name. The package
is listed alongside each module name in the combined contents.
* Entities which are re-exported from another package now at least
leave a hyperlink in the generated HTML, rather than nothing at all.
* Some fixes for bugs which caused incorrect hyperlinks in the
generated HTML. In particular, instances should now be linked
correctly.
* Some aesthetic improvements to the generated HTML.
-----------------------------------------------------------------------------
## Changes in version 0.5:
* Compiles with recent versions of GHC.
* A few bugs have been fixed.
* New labelling/linking feature (see "Anchors" in the manual).
-----------------------------------------------------------------------------
## Changes in version 0.4:
* Import declarations which list entities in parentheses, or with
hiding clauses, are now properly supported. Modulo one or two
small infelicities, the full Haskell modules system is now supported.
* Haddock is now more flexible about the placing of separators
(commas, semicolons) in relation to doc comments.
* There is support for generating and reading "interface files"
which describe the exports of a set of modules. This is useful
for generating documentation which hyperlinks to
previously-generated documentation.
* Support for generating the extra files required by the Microsoft
Help compiler.
* New option: --prologue specifies a file of documentation which is
placed on the contents page.
* Many bugs fixed
-----------------------------------------------------------------------------
## Changes in version 0.3:
* Documentation on individual function arguments is now implemented
* Links can be made to identifiers that aren't in scope, by using
the fully qualified name.
* Instances are collected and listed with the appropriate classes
and datatypes (not for derived instances yet).
* Single quotes are only interpreted specially when they surround a
legal Haskell identifier, otherwise they are treated literally.
* Bird-tracked text is now literal. If you want marked-up text in
a code block, use the @...@ notation instead.
* Various changes to the layout, it generally looks nicer now.
* Various bugs fixed.
-----------------------------------------------------------------------------
## Changes in version 0.2:
* The [...] markup for typewriter font has been changed to @...@.
* Module attributes introduced (see the documentation for details).
* {- ... -} style comments may now be used for documentation annotations
* Recursive modules are detected and reported as an error.
* Existential constructors and rank-N types are now groked by the parser
* Some type rendering cleaned up
* `abc' is accepted as well as 'abc' to markup an identifier
* Several bugs fixed, and error messages improved.
CODE_OF_CONDUCT.md 0 → 100644
View file @ c9bc29c6
# Conduct
* We are committed to providing a friendly, safe and welcoming environment for all, regardless of level of experience,
gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age,
religion, nationality, or other similar characteristic.
* Please avoid using overtly sexual aliases or other nicknames that might detract from a friendly, safe
and welcoming environment for all.
* Please be kind and courteous. There’s no need to be mean or rude.
* Respect that people have differences of opinion and that every design or implementation choice carries a trade-off
and numerous costs. There is seldom a right answer.
* Please keep unstructured critique to a minimum. If you have solid ideas you want to experiment with,
make a fork and see how it works.
* We will exclude you from interaction if you insult, demean or harass anyone. That is not welcome behavior.
We interpret the term “harassment” as including the definition in the [Citizen Code of Conduct][CCC];
if you have any lack of clarity about what might be included in that concept, please read their definition.
In particular, we don’t tolerate behavior that excludes people in socially marginalized groups.
* Private harassment is also unacceptable. No matter who you are, if you feel you have been or are being harassed or
made uncomfortable by a community member, please contact one of the maintainers or any of the
Core Team immediately. Whether you’re a regular contributor or a newcomer,
we care about making this community a safe place for you and we’ve got your back.
* Likewise any spamming, trolling, flaming, baiting or other attention-stealing behavior is not welcome.
_Adapted from the [Rust Lang][Rust CoC]'s code of conduct_
[CCC]: https://github.com/stumpsyn/policies/blob/master/citizen_code_of_conduct.md
[Rust CoC]: https://www.rust-lang.org/policies/code-of-conduct
CONTRIBUTING.md 0 → 100644
View file @ c9bc29c6
# Contributing to Haddock
Thank you for contributing to Haddock! Here is the information you will need in
order to make your contribution
## Code of Conduct
We need you to read, acknowledge, and abide by our [Code of Conduct][CoC].
## Reporting issues
Please open a ticket if you get an unexpected behaviour from Haddock!
You should ideally include a [Short, Self Contained, Correct (Compilable), Example][SSCCE]
in your ticket, so that the maintainers may easily reproduce your issue.
Here is a list of things you should include in your ticket
* Your GHC version.
* Your platform, OS and distribution if applicable.
* Your cabal version if applicable.
* Include any other info you think might be relevant (sandbox? unusual setup?).
## Hacking
To get started you'll need the latest GHC release installed.
Clone the repository:
```bash
git clone https://github.com/haskell/haddock.git
cd haddock
```
### Git Branches
If your patch consists of glue code and interface changes with GHC, please
open a Pull Request targeting the `ghc-head` branch.
Otherwise, for improvements to the documentation generator,
please base your pull request on the current GHC version branch
(`ghc-9.0` for instance). The PR will be forward-ported to `ghc-head`
so that documentation built within GHC can benefit from it.
### Building the packages
#### Using `cabal`
Requires cabal `>= 3.4` and GHC `== 9.4`:
You can install the latest build of GHC via ghcup using this command:
```bash
ghcup install ghc -u "https://gitlab.haskell.org/ghc/ghc/-/jobs/artifacts/master/raw/ghc-x86_64-deb9-linux-integer-simple.tar.xz?job=validate-x86_64-linux-deb9-integer-simple" head
```
```bash
cabal v2-build all --enable-tests
cabal v2-test all
```
### Updating golden testsuite outputs
If you've changed Haddock's output, you will probably need to accept the new
output of Haddock's golden test suites (`html-test`, `latex-test`,
`hoogle-test`, and `hypsrc-test`). This can be done by passing the `--accept`
argument to these test suites. With a new enough version of `cabal-install`:
```
cabal v2-test html-test latex-test hoogle-test hypsrc-test \
--test-option='--accept'
```
[SSCCE]: http://sscce.org/
[CoC]: ./CODE_OF_CONDUCT.md
LICENSE
View file @ c9bc29c6
Copyright 2002, Simon Marlow. All rights reserved. Copyright (c) 2002-2010, Simon Marlow
All rights reserved.
Redistribution and use in source and binary forms, with or without Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met: modification, are permitted provided that the following conditions are
met:
- Redistributions of source code must retain the above copyright notice, 1. Redistributions of source code must retain the above copyright
this list of conditions and the following disclaimer. notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, 2. Redistributions in binary form must reproduce the above copyright
this list of conditions and the following disclaimer in the documentation notice, this list of conditions and the following disclaimer in the
and/or other materials provided with the distribution. documentation and/or other materials provided with the
distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Makefile
View file @ c9bc29c6
TOP = . # -----------------------------------------------------------------------------
include $(TOP)/mk/boilerplate.mk #
# (c) 2009 The University of Glasgow
#
# This file is part of the GHC build system.
#
# To understand how the build system works and how to modify it, see
# http://ghc.haskell.org/trac/ghc/wiki/Building/Architecture
# http://ghc.haskell.org/trac/ghc/wiki/Building/Modifying
#
# -----------------------------------------------------------------------------
SUBDIRS = src html dir = utils/haddock
TOP = ../..
include $(TOP)/mk/target.mk include $(TOP)/mk/sub-makefile.mk
README deleted 100644 → 0
View file @ 1c0a3bed
Haddock, a Haskell Documentation Tool
=====================================
This is Haddock, a tool for automatically generating documentation
from annotated Haskell source code. It is primary intended for
documenting library interfaces, but it should be useful for any kind
of Haskell code.
Like other systems ([1],[2]), Haddock lets you write documentation
annotations next to the definitions of functions and types in the
source code, in a syntax that is easy on the eye when writing the
source code (no heavyweight mark-up). The documentation generated by
Haddock is fully hyperlinked - click on a type name in a type
signature to go straight to the definition, and documentation, for
that type.
Haddock understands Haskell's module system, so you can structure your
code however you like without worrying that internal structure will be
exposed in the generated documentation. For example, it is common to
implement a library in several modules, but define the external API by
having a single module which re-exports parts of these implementation
modules. Using Haddock, you can still write documentation annotations
next to the actual definitions of the functions and types in the
library, but the documentation annotations from the implementation
will be propagated to the external API when the documentation is
generated. Abstract types and classes are handled correctly. In
fact, even without any documentation annotations, Haddock can generate
useful documentation from your source code.
Haddock can generate documentation in multiple formats; currently HTML
is implemented, and there is partial support for generating DocBook.
The generated HTML uses stylesheets, so you need a fairly up-to-date
browser to view it properly (Mozilla, Konqueror, Opera, and IE 6
should all be ok).
Full documentation can be found in the doc/ subdirectory, in DocBook
format.
Please send questions and suggestions to me:
Simon Marlow <simonmar@microsoft.com>
System Requirements
===================
Haddock currently requires GHC version 4.08 or later to compile.
[1] IDoc - A No Frills Haskell Interface Documentation System
http://www.cse.unsw.edu.au/~chak/haskell/idoc/
[2] HDoc http://www.fmi.uni-passau.de/~groessli/hdoc/
README.md 0 → 100644
View file @ c9bc29c6
# Haddock [![CI][CI badge]][CI page] [![Hackage][Hackage badge]][Hackage page]
Haddock is the standard tool for generating documentation from Haskell code.
Full documentation about Haddock itself can be found in the `doc/` subdirectory,
in [reStructuredText][reST] format.
## Project overview
This project consists of three packages:
* `haddock`: provides the `haddock` executable. It is implemented as a tiny
wrapper around `haddock-api`'s `Documentation.Haddock.haddock` function.
* `haddock-api`: contains the program logic of the `haddock` tool.
[The haddocks for the `Documentation.Haddock` module][Documentation.Haddock]
offer a good overview of the functionality.
* `haddock-library`: is concerned with the parsing and processing of the
Haddock markup language. Unlike the other packages, it is expected to build
on a fairly wide range of GHC versions.
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) to see how to make contributions to the
project.
[CI page]: https://github.com/haskell/haddock/actions/workflows/ci.yml
[CI badge]: https://github.com/haskell/haddock/actions/workflows/ci.yml/badge.svg
[Hackage page]: https://hackage.haskell.org/package/haddock
[Hackage badge]: https://img.shields.io/hackage/v/haddock.svg
[reST]: https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
[Documentation.Haddock]: http://hackage.haskell.org/package/haddock-api/docs/Documentation-Haddock.html
[cabal v2]: https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html
Setup.lhs 0 → 100755
View file @ c9bc29c6
#!/usr/bin/env runhaskell
> import Distribution.Simple
> main = defaultMain
TODO deleted 100644 → 0
View file @ 1c0a3bed
* when exporting a class method on its own, don't list the whole class in
the export list (we should try to construct the type of the method, somehow).
* Allow linking to a section name?
* Class names aren't rendered as proper binders
* for a constructor, don't fill its entire cell with a grey background.
* don't link to M.x if M.x is re-exported via a 'module N' from module M.
* switch to longer rendering form for datatypes when necessary?
* Pick the preferred export names as per the paper.
* Top-level package docs
* instances: need to construct instances for deriving clauses, somehow.
* attributes for individual declarations, eg.
-- #abstract
or targetted to a specific decl:
-- #T: abstract
#long, #short, #noinstances (on a type or class)
* A module re-export should only reference the target module if the
target module is imported without hiding any of its exports (otherwise
we should inline just the exported bits).
* facilities for saving interfaces so that you can run Haddock against
something that isn't the Prelude.
* Do the unlitting/CPPing from Haddock itself so we get the source file
links right.
* Allow documentation annotations to explicitly name the entity they
refer to.
* Add back-references from the definition to the uses of types/classes
(perhaps in the index?)
* In the contents page, indicate portability/stability of each module
somehow.
* remove extra whitespace from the generated HTML to save space
* split large modules into several pages (perhaps split at each
section 1 heading?)
* pay attention to import specs!
* include file revision info in module headers
* Add a link to the defining location of a re-exported entity
* fixities
* we don't deal with records properly - exporting record selectors etc.
* remove the s/r conflicts I added to the grammar
* check handling of special types ([], (), (,) etc.)
* Horizontal lines?
* clean up the layout: don't use table cellspacing, use CSS instead
* Support for the rest of GHC extensions in the parser:
- implicit parameters
- scoped type variables (return types left to do).
cabal.project 0 → 100644
View file @ c9bc29c6
with-compiler: ghc-9.7
packages: ./
./haddock-api
./haddock-library
./haddock-test
test-show-details: direct
allow-newer:
ghc-paths:Cabal,
*:base,
*:ghc-prim,
tree-diff:time
package haddock-library
tests: False
package haddock-api
tests: False
-- Pinning the index-state helps to make reasonably CI deterministic
index-state: 2023-05-22T15:14:29Z
doc/.gitignore 0 → 100644
View file @ c9bc29c6
.build-html
\ No newline at end of file
doc/Makefile
View file @ c9bc29c6
TOP=.. SPHINX_BUILD ?= sphinx-build
include $(TOP)/mk/boilerplate.mk
SGML_DOC = haddock all : html
include $(TOP)/mk/target.mk .PHONY : html
html :
$(SPHINX_BUILD) -b html . .build-html
doc/README.md 0 → 100644
View file @ c9bc29c6
# Haddock documentation
The documentation is in ReStructuredText format. You need
[Sphinx](http://www.sphinx-doc.org/) to process it. To build the HTML
documentation,
$ make html
which leaves the HTML documentation the `.build-html/` subdirectory.
doc/cheatsheet/LICENSE 0 → 100644
View file @ c9bc29c6
Attribution-ShareAlike 4.0 International
=======================================================================
Creative Commons Corporation ("Creative Commons") is not a law firm and
does not provide legal services or legal advice. Distribution of
Creative Commons public licenses does not create a lawyer-client or
other relationship. Creative Commons makes its licenses and related
information available on an "as-is" basis. Creative Commons gives no
warranties regarding its licenses, any material licensed under their
terms and conditions, or any related information. Creative Commons
disclaims all liability for damages resulting from their use to the
fullest extent possible.
Using Creative Commons Public Licenses
Creative Commons public licenses provide a standard set of terms and
conditions that creators and other rights holders may use to share
original works of authorship and other material subject to copyright
and certain other rights specified in the public license below. The
following considerations are for informational purposes only, are not
exhaustive, and do not form part of our licenses.
Considerations for licensors: Our public licenses are
intended for use by those authorized to give the public
permission to use material in ways otherwise restricted by
copyright and certain other rights. Our licenses are
irrevocable. Licensors should read and understand the terms
and conditions of the license they choose before applying it.
Licensors should also secure all rights necessary before
applying our licenses so that the public can reuse the
material as expected. Licensors should clearly mark any
material not subject to the license. This includes other CC-
licensed material, or material used under an exception or
limitation to copyright. More considerations for licensors:
wiki.creativecommons.org/Considerations_for_licensors
Considerations for the public: By using one of our public
licenses, a licensor grants the public permission to use the
licensed material under specified terms and conditions. If
the licensor's permission is not necessary for any reason--for
example, because of any applicable exception or limitation to
copyright--then that use is not regulated by the license. Our
licenses grant only permissions under copyright and certain
other rights that a licensor has authority to grant. Use of
the licensed material may still be restricted for other
reasons, including because others have copyright or other
rights in the material. A licensor may make special requests,
such as asking that all changes be marked or described.
Although not required by our licenses, you are encouraged to
respect those requests where reasonable. More_considerations
for the public:
wiki.creativecommons.org/Considerations_for_licensees
=======================================================================
Creative Commons Attribution-ShareAlike 4.0 International Public
License
By exercising the Licensed Rights (defined below), You accept and agree
to be bound by the terms and conditions of this Creative Commons
Attribution-ShareAlike 4.0 International Public License ("Public
License"). To the extent this Public License may be interpreted as a
contract, You are granted the Licensed Rights in consideration of Your
acceptance of these terms and conditions, and the Licensor grants You
such rights in consideration of benefits the Licensor receives from
making the Licensed Material available under these terms and
conditions.
Section 1 -- Definitions.
a. Adapted Material means material subject to Copyright and Similar
Rights that is derived from or based upon the Licensed Material
and in which the Licensed Material is translated, altered,
arranged, transformed, or otherwise modified in a manner requiring
permission under the Copyright and Similar Rights held by the
Licensor. For purposes of this Public License, where the Licensed
Material is a musical work, performance, or sound recording,
Adapted Material is always produced where the Licensed Material is
synched in timed relation with a moving image.
b. Adapter's License means the license You apply to Your Copyright
and Similar Rights in Your contributions to Adapted Material in
accordance with the terms and conditions of this Public License.
c. BY-SA Compatible License means a license listed at
creativecommons.org/compatiblelicenses, approved by Creative
Commons as essentially the equivalent of this Public License.
d. Copyright and Similar Rights means copyright and/or similar rights
closely related to copyright including, without limitation,
performance, broadcast, sound recording, and Sui Generis Database
Rights, without regard to how the rights are labeled or
categorized. For purposes of this Public License, the rights
specified in Section 2(b)(1)-(2) are not Copyright and Similar
Rights.
e. Effective Technological Measures means those measures that, in the
absence of proper authority, may not be circumvented under laws
fulfilling obligations under Article 11 of the WIPO Copyright
Treaty adopted on December 20, 1996, and/or similar international
agreements.
f. Exceptions and Limitations means fair use, fair dealing, and/or
any other exception or limitation to Copyright and Similar Rights
that applies to Your use of the Licensed Material.
g. License Elements means the license attributes listed in the name
of a Creative Commons Public License. The License Elements of this
Public License are Attribution and ShareAlike.
h. Licensed Material means the artistic or literary work, database,
or other material to which the Licensor applied this Public
License.
i. Licensed Rights means the rights granted to You subject to the
terms and conditions of this Public License, which are limited to
all Copyright and Similar Rights that apply to Your use of the
Licensed Material and that the Licensor has authority to license.
j. Licensor means the individual(s) or entity(ies) granting rights
under this Public License.
k. Share means to provide material to the public by any means or
process that requires permission under the Licensed Rights, such
as reproduction, public display, public performance, distribution,
dissemination, communication, or importation, and to make material
available to the public including in ways that members of the
public may access the material from a place and at a time
individually chosen by them.
l. Sui Generis Database Rights means rights other than copyright
resulting from Directive 96/9/EC of the European Parliament and of
the Council of 11 March 1996 on the legal protection of databases,
as amended and/or succeeded, as well as other essentially
equivalent rights anywhere in the world.
m. You means the individual or entity exercising the Licensed Rights
under this Public License. Your has a corresponding meaning.
Section 2 -- Scope.
a. License grant.
1. Subject to the terms and conditions of this Public License,
the Licensor hereby grants You a worldwide, royalty-free,
non-sublicensable, non-exclusive, irrevocable license to
exercise the Licensed Rights in the Licensed Material to:
a. reproduce and Share the Licensed Material, in whole or
in part; and
b. produce, reproduce, and Share Adapted Material.
2. Exceptions and Limitations. For the avoidance of doubt, where
Exceptions and Limitations apply to Your use, this Public
License does not apply, and You do not need to comply with
its terms and conditions.
3. Term. The term of this Public License is specified in Section
6(a).
4. Media and formats; technical modifications allowed. The
Licensor authorizes You to exercise the Licensed Rights in
all media and formats whether now known or hereafter created,
and to make technical modifications necessary to do so. The
Licensor waives and/or agrees not to assert any right or
authority to forbid You from making technical modifications
necessary to exercise the Licensed Rights, including
technical modifications necessary to circumvent Effective
Technological Measures. For purposes of this Public License,
simply making modifications authorized by this Section 2(a)
(4) never produces Adapted Material.
5. Downstream recipients.
a. Offer from the Licensor -- Licensed Material. Every
recipient of the Licensed Material automatically
receives an offer from the Licensor to exercise the
Licensed Rights under the terms and conditions of this
Public License.
b. Additional offer from the Licensor -- Adapted Material.
Every recipient of Adapted Material from You
automatically receives an offer from the Licensor to
exercise the Licensed Rights in the Adapted Material
under the conditions of the Adapter's License You apply.
c. No downstream restrictions. You may not offer or impose
any additional or different terms or conditions on, or
apply any Effective Technological Measures to, the
Licensed Material if doing so restricts exercise of the
Licensed Rights by any recipient of the Licensed
Material.
6. No endorsement. Nothing in this Public License constitutes or
may be construed as permission to assert or imply that You
are, or that Your use of the Licensed Material is, connected
with, or sponsored, endorsed, or granted official status by,
the Licensor or others designated to receive attribution as
provided in Section 3(a)(1)(A)(i).
b. Other rights.
1. Moral rights, such as the right of integrity, are not
licensed under this Public License, nor are publicity,
privacy, and/or other similar personality rights; however, to
the extent possible, the Licensor waives and/or agrees not to
assert any such rights held by the Licensor to the limited
extent necessary to allow You to exercise the Licensed
Rights, but not otherwise.
2. Patent and trademark rights are not licensed under this
Public License.
3. To the extent possible, the Licensor waives any right to
collect royalties from You for the exercise of the Licensed
Rights, whether directly or through a collecting society
under any voluntary or waivable statutory or compulsory
licensing scheme. In all other cases the Licensor expressly
reserves any right to collect such royalties.
Section 3 -- License Conditions.
Your exercise of the Licensed Rights is expressly made subject to the
following conditions.
a. Attribution.
1. If You Share the Licensed Material (including in modified
form), You must:
a. retain the following if it is supplied by the Licensor
with the Licensed Material:
i. identification of the creator(s) of the Licensed
Material and any others designated to receive
attribution, in any reasonable manner requested by
the Licensor (including by pseudonym if
designated);
ii. a copyright notice;
iii. a notice that refers to this Public License;
iv. a notice that refers to the disclaimer of
warranties;
v. a URI or hyperlink to the Licensed Material to the
extent reasonably practicable;
b. indicate if You modified the Licensed Material and
retain an indication of any previous modifications; and
c. indicate the Licensed Material is licensed under this
Public License, and include the text of, or the URI or
hyperlink to, this Public License.
2. You may satisfy the conditions in Section 3(a)(1) in any
reasonable manner based on the medium, means, and context in
which You Share the Licensed Material. For example, it may be
reasonable to satisfy the conditions by providing a URI or
hyperlink to a resource that includes the required
information.
3. If requested by the Licensor, You must remove any of the
information required by Section 3(a)(1)(A) to the extent
reasonably practicable.
b. ShareAlike.
In addition to the conditions in Section 3(a), if You Share
Adapted Material You produce, the following conditions also apply.
1. The Adapter's License You apply must be a Creative Commons
license with the same License Elements, this version or
later, or a BY-SA Compatible License.
2. You must include the text of, or the URI or hyperlink to, the
Adapter's License You apply. You may satisfy this condition
in any reasonable manner based on the medium, means, and
context in which You Share Adapted Material.
3. You may not offer or impose any additional or different terms
or conditions on, or apply any Effective Technological
Measures to, Adapted Material that restrict exercise of the
rights granted under the Adapter's License You apply.
Section 4 -- Sui Generis Database Rights.
Where the Licensed Rights include Sui Generis Database Rights that
apply to Your use of the Licensed Material:
a. for the avoidance of doubt, Section 2(a)(1) grants You the right
to extract, reuse, reproduce, and Share all or a substantial
portion of the contents of the database;
b. if You include all or a substantial portion of the database
contents in a database in which You have Sui Generis Database
Rights, then the database in which You have Sui Generis Database
Rights (but not its individual contents) is Adapted Material,
including for purposes of Section 3(b); and
c. You must comply with the conditions in Section 3(a) if You Share
all or a substantial portion of the contents of the database.
For the avoidance of doubt, this Section 4 supplements and does not
replace Your obligations under this Public License where the Licensed
Rights include other Copyright and Similar Rights.
Section 5 -- Disclaimer of Warranties and Limitation of Liability.
a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
c. The disclaimer of warranties and limitation of liability provided
above shall be interpreted in a manner that, to the extent
possible, most closely approximates an absolute disclaimer and
waiver of all liability.
Section 6 -- Term and Termination.
a. This Public License applies for the term of the Copyright and
Similar Rights licensed here. However, if You fail to comply with
this Public License, then Your rights under this Public License
terminate automatically.
b. Where Your right to use the Licensed Material has terminated under
Section 6(a), it reinstates:
1. automatically as of the date the violation is cured, provided
it is cured within 30 days of Your discovery of the
violation; or
2. upon express reinstatement by the Licensor.
For the avoidance of doubt, this Section 6(b) does not affect any
right the Licensor may have to seek remedies for Your violations
of this Public License.
c. For the avoidance of doubt, the Licensor may also offer the
Licensed Material under separate terms or conditions or stop
distributing the Licensed Material at any time; however, doing so
will not terminate this Public License.
d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
License.
Section 7 -- Other Terms and Conditions.
a. The Licensor shall not be bound by any additional or different
terms or conditions communicated by You unless expressly agreed.
b. Any arrangements, understandings, or agreements regarding the
Licensed Material not stated herein are separate from and
independent of the terms and conditions of this Public License.
Section 8 -- Interpretation.
a. For the avoidance of doubt, this Public License does not, and
shall not be interpreted to, reduce, limit, restrict, or impose
conditions on any use of the Licensed Material that could lawfully
be made without permission under this Public License.
b. To the extent possible, if any provision of this Public License is
deemed unenforceable, it shall be automatically reformed to the
minimum extent necessary to make it enforceable. If the provision
cannot be reformed, it shall be severed from this Public License
without affecting the enforceability of the remaining terms and
conditions.
c. No term or condition of this Public License will be waived and no
failure to comply consented to unless expressly agreed to by the
Licensor.
d. Nothing in this Public License constitutes or may be interpreted
as a limitation upon, or waiver of, any privileges and immunities
that apply to the Licensor or You, including from the legal
processes of any jurisdiction or authority.
=======================================================================
Creative Commons is not a party to its public
licenses. Notwithstanding, Creative Commons may elect to apply one of
its public licenses to material it publishes and in those instances
will be considered the “Licensor.” The text of the Creative Commons
public licenses is dedicated to the public domain under the CC0 Public
Domain Dedication. Except for the limited purpose of indicating that
material is shared under a Creative Commons public license or as
otherwise permitted by the Creative Commons policies published at
creativecommons.org/policies, Creative Commons does not authorize the
use of the trademark "Creative Commons" or any other trademark or logo
of Creative Commons without its prior written consent including,
without limitation, in connection with any unauthorized modifications
to any of its public licenses or any other arrangements,
understandings, or agreements concerning use of licensed material. For
the avoidance of doubt, this paragraph does not form part of the
public licenses.
Creative Commons may be contacted at creativecommons.org.