Add notices and DEVNOTES flag
* .gitignore (/config.*): Restrict to root. * configure.ac (DEVNOTES): Add variable. (--enable-devnotes): Add configuration flag. * doc/Makefile.am (liza_TEXINFOS): config.texi dependency. * doc/config.texi.in: Add configuration file. * doc/liza.css: Styling for notices. * doc/liza.texi: Include configuration. Add notice for DEVNOTES. * doc/macros.texi: Add notice macros. * doc/.gitignore (config.texi): Ignore generated file.master
parent
00e2389a5f
commit
1b4ebc13e3
|
@ -7,7 +7,7 @@ Makefile.in
|
||||||
|
|
||||||
# generated by configure
|
# generated by configure
|
||||||
src/version.js
|
src/version.js
|
||||||
config.*
|
/config.*
|
||||||
Makefile
|
Makefile
|
||||||
package.json
|
package.json
|
||||||
|
|
||||||
|
|
13
configure.ac
13
configure.ac
|
@ -41,6 +41,17 @@ AS_IF([node --harmony_destructuring >/dev/null 2>/dev/null],
|
||||||
AC_SUBST([NODE_DESTRUCTURE], [--harmony_destructuring])],
|
AC_SUBST([NODE_DESTRUCTURE], [--harmony_destructuring])],
|
||||||
[AC_MSG_RESULT(no)])
|
[AC_MSG_RESULT(no)])
|
||||||
|
|
||||||
|
set_devnotes='@set DEVNOTES'
|
||||||
|
AC_ARG_ENABLE(
|
||||||
|
[devnotes],
|
||||||
|
[AS_HELP_STRING([--enable-devnotes],
|
||||||
|
[include note for liza developers (enabled by default)])],
|
||||||
|
[test "x$enableval" != xno || set_devnotes="@c $set_devnotes"])
|
||||||
|
|
||||||
|
AC_SUBST([SET_DEVNOTES], [$set_devnotes])
|
||||||
|
|
||||||
# generate files from their *.in counterparts
|
# generate files from their *.in counterparts
|
||||||
AC_CONFIG_FILES([Makefile doc/Makefile package.json src/version.js])
|
AC_CONFIG_FILES([Makefile package.json
|
||||||
|
doc/Makefile doc/config.texi
|
||||||
|
src/version.js])
|
||||||
AC_OUTPUT
|
AC_OUTPUT
|
||||||
|
|
|
@ -19,3 +19,4 @@ Makefile
|
||||||
Makefile.in
|
Makefile.in
|
||||||
stamp-vti
|
stamp-vti
|
||||||
version.texi
|
version.texi
|
||||||
|
config.texi
|
||||||
|
|
|
@ -21,5 +21,4 @@
|
||||||
MAKEINFOHTML = $(MAKEINFO) --html --css-include liza.css
|
MAKEINFOHTML = $(MAKEINFO) --html --css-include liza.css
|
||||||
|
|
||||||
info_TEXINFOS = liza.texi
|
info_TEXINFOS = liza.texi
|
||||||
liza_TEXINFOS = design.texi macros.texi
|
liza_TEXINFOS = design.texi macros.texi config.texi
|
||||||
|
|
||||||
|
|
|
@ -0,0 +1,4 @@
|
||||||
|
@c Manual configuration
|
||||||
|
|
||||||
|
@c whether to include notes for Liza developers
|
||||||
|
@SET_DEVNOTES@
|
34
doc/liza.css
34
doc/liza.css
|
@ -1,5 +1,6 @@
|
||||||
/*
|
/*
|
||||||
Copyright (C) 2016-2017 Oliver Heimlich
|
Copyright (C) 2016-2017 Oliver Heimlich
|
||||||
|
Copyright (C) 2017 LoVullo Associates, Inc.
|
||||||
|
|
||||||
This file is part of Octave.
|
This file is part of Octave.
|
||||||
|
|
||||||
|
@ -110,3 +111,36 @@ but don't sacrifice space on small screens.
|
||||||
body { margin-left: 7.5em; }
|
body { margin-left: 7.5em; }
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/** added by LoVullo Associates **/
|
||||||
|
.doc-notice
|
||||||
|
{
|
||||||
|
border-left: 5px solid #657b83;
|
||||||
|
margin: 0px;
|
||||||
|
padding: 0em 0em 0em 0.25em;
|
||||||
|
padding-block-start: 0.25em;
|
||||||
|
padding-block-end: 0.25em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.doc-notice p
|
||||||
|
{
|
||||||
|
margin: 0px;
|
||||||
|
}
|
||||||
|
|
||||||
|
.doc-notice.dev
|
||||||
|
{
|
||||||
|
border-color: #d33682;
|
||||||
|
}
|
||||||
|
|
||||||
|
.doc-notice.dev p::before
|
||||||
|
{
|
||||||
|
color: #d33682;
|
||||||
|
content: '\01F6A7';
|
||||||
|
margin-right: 0.5em;
|
||||||
|
}
|
||||||
|
|
||||||
|
.footnote-notice.dev p:first-child::before
|
||||||
|
{
|
||||||
|
content: '\01F6A7';
|
||||||
|
margin-right: 0.5em;
|
||||||
|
}
|
||||||
|
|
|
@ -10,7 +10,12 @@
|
||||||
@c Free Documentation License''.
|
@c Free Documentation License''.
|
||||||
|
|
||||||
@c %**start of header
|
@c %**start of header
|
||||||
|
@include config.texi
|
||||||
@include version.texi
|
@include version.texi
|
||||||
|
@include macros.texi
|
||||||
|
|
||||||
|
@c Developer Notes index (used only if DEVNOTES)
|
||||||
|
@defindex dn
|
||||||
|
|
||||||
@setfilename liza.info
|
@setfilename liza.info
|
||||||
@settitle Liza Data Collection Framework v@value{VERSION}
|
@settitle Liza Data Collection Framework v@value{VERSION}
|
||||||
|
@ -47,6 +52,12 @@ Free Documentation License''.
|
||||||
@insertcopying
|
@insertcopying
|
||||||
@end titlepage
|
@end titlepage
|
||||||
|
|
||||||
|
@devnotice{
|
||||||
|
This manual contains inline notes for developers of Liza.@footnote{
|
||||||
|
To disable for user documentation, pass @option{--disable-devnotes}
|
||||||
|
to @command{configure}.}
|
||||||
|
For an index of notes@comma{} see @ref{Developer Notes Index}.}
|
||||||
|
|
||||||
@contents
|
@contents
|
||||||
|
|
||||||
@ifnottex
|
@ifnottex
|
||||||
|
@ -57,6 +68,9 @@ Free Documentation License''.
|
||||||
@menu
|
@menu
|
||||||
* Design and Architecture:Design. Design and structure of framework
|
* Design and Architecture:Design. Design and structure of framework
|
||||||
* Concept Index::
|
* Concept Index::
|
||||||
|
@ifset DEVNOTES
|
||||||
|
* Developer Notes Index:: Index of pertenant notes for developers of Liza.
|
||||||
|
@end ifset
|
||||||
@end menu
|
@end menu
|
||||||
|
|
||||||
@ifnottex
|
@ifnottex
|
||||||
|
@ -64,11 +78,17 @@ Free Documentation License''.
|
||||||
@insertcopying
|
@insertcopying
|
||||||
@end ifnottex
|
@end ifnottex
|
||||||
|
|
||||||
@include macros.texi
|
|
||||||
@include design.texi
|
@include design.texi
|
||||||
|
|
||||||
@node Concept Index
|
@node Concept Index
|
||||||
@unnumbered Concept Index
|
@unnumbered Concept Index
|
||||||
@printindex cp
|
@printindex cp
|
||||||
|
|
||||||
|
@ifset DEVNOTES
|
||||||
|
@node Developer Notes Index
|
||||||
|
@unnumbered Developer Notes Index
|
||||||
|
@printindex dn
|
||||||
|
@end ifset
|
||||||
|
|
||||||
|
|
||||||
@bye
|
@bye
|
||||||
|
|
|
@ -8,22 +8,88 @@
|
||||||
@c Texts. A copy of the license is included in the section entitled ``GNU
|
@c Texts. A copy of the license is included in the section entitled ``GNU
|
||||||
@c Free Documentation License''.
|
@c Free Documentation License''.
|
||||||
|
|
||||||
@c insert appropriate em dash for mode
|
|
||||||
@iftex
|
|
||||||
@macro mdash{}
|
|
||||||
---
|
|
||||||
@end macro
|
|
||||||
@end iftex
|
|
||||||
|
|
||||||
|
@c unicode CONSTRUCTION SIGN
|
||||||
|
@macro constructionsign
|
||||||
|
🚧
|
||||||
|
@end macro
|
||||||
|
|
||||||
|
|
||||||
|
@c insert appropriate em dash for mode
|
||||||
@ifnottex
|
@ifnottex
|
||||||
@macro mdash{}
|
@macro mdash
|
||||||
—
|
@inlinefmtifelse{html, @inlineraw{html,—}, —}
|
||||||
@end macro
|
@end macro
|
||||||
@end ifnottex
|
@end ifnottex
|
||||||
|
|
||||||
|
@c the macro for TeX for some reason always seems to be followed
|
||||||
|
@c by a space when applied; #1 consumes it and re-adds if it's
|
||||||
|
@c not empty
|
||||||
|
@tex
|
||||||
|
\gdef\mdash#1{%
|
||||||
|
---%
|
||||||
|
\def\next{#1}%
|
||||||
|
\ifx\next\empty\relax\else#1\fi%
|
||||||
|
}
|
||||||
|
@end tex
|
||||||
|
|
||||||
|
|
||||||
|
@c inline documentation notice for some sort of quality
|
||||||
|
@c improvement or warning
|
||||||
|
@macro rawnotice{type,text}
|
||||||
|
@html
|
||||||
|
<div class="doc-notice \type\">
|
||||||
|
@end html
|
||||||
|
@emph{\text\}
|
||||||
|
@html
|
||||||
|
</div>
|
||||||
|
@end html
|
||||||
|
@end macro
|
||||||
|
|
||||||
|
|
||||||
|
@c vanilla notice
|
||||||
|
@macro notice{text}
|
||||||
|
@rawnotice{{},\text\}
|
||||||
|
@end macro
|
||||||
|
|
||||||
|
|
||||||
|
@c notice for developers of liza
|
||||||
|
@macro devnotice{text}
|
||||||
|
@ifset DEVNOTES
|
||||||
|
@html
|
||||||
|
@end html
|
||||||
|
@rawnotice{dev,\text\}
|
||||||
|
@end ifset
|
||||||
|
@end macro
|
||||||
|
|
||||||
|
|
||||||
@c indicate that help is needed to produce docs
|
@c indicate that help is needed to produce docs
|
||||||
@macro helpwanted{}
|
@macro helpwanted{}
|
||||||
@cindex TODO, Missing Docs
|
@cindex TODO, Missing Docs
|
||||||
@emph{There's nothing here yet. Maybe you can help?}
|
@dnindex Missing Docs
|
||||||
|
@notice{There's nothing here yet. Maybe you can help?}
|
||||||
|
@end macro
|
||||||
|
|
||||||
|
|
||||||
|
@c maintenance note for developers
|
||||||
|
@macro maintenance{desc}
|
||||||
|
@dnindex Maintenance Concern
|
||||||
|
@devnotice{This system has maintenance concerns.@footnote{
|
||||||
|
@maintfoot{\desc\}
|
||||||
|
}}
|
||||||
|
@end macro
|
||||||
|
|
||||||
|
@c encapsulated to avoid bad TeX generation (fails compilation
|
||||||
|
@c when inlined at call site)
|
||||||
|
@macro maintfoot{desc}
|
||||||
|
@html
|
||||||
|
<div class="footnote-notice dev">
|
||||||
|
@end html
|
||||||
|
\desc\
|
||||||
|
|
||||||
|
@emph{Developers should evaluate whether extra time should be
|
||||||
|
allocated for tasks involving this system.}
|
||||||
|
@html
|
||||||
|
</div>
|
||||||
|
@end html
|
||||||
@end macro
|
@end macro
|
||||||
|
|
Loading…
Reference in New Issue