1
0
Fork 0

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
Mike Gerwitz 2017-03-21 10:27:36 -04:00
parent 00e2389a5f
commit 1b4ebc13e3
8 changed files with 149 additions and 14 deletions

2
.gitignore vendored
View File

@ -7,7 +7,7 @@ Makefile.in
# generated by configure
src/version.js
config.*
/config.*
Makefile
package.json

View File

@ -41,6 +41,17 @@ AS_IF([node --harmony_destructuring >/dev/null 2>/dev/null],
AC_SUBST([NODE_DESTRUCTURE], [--harmony_destructuring])],
[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
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

1
doc/.gitignore vendored
View File

@ -19,3 +19,4 @@ Makefile
Makefile.in
stamp-vti
version.texi
config.texi

View File

@ -21,5 +21,4 @@
MAKEINFOHTML = $(MAKEINFO) --html --css-include liza.css
info_TEXINFOS = liza.texi
liza_TEXINFOS = design.texi macros.texi
liza_TEXINFOS = design.texi macros.texi config.texi

View File

@ -0,0 +1,4 @@
@c Manual configuration
@c whether to include notes for Liza developers
@SET_DEVNOTES@

View File

@ -1,5 +1,6 @@
/*
Copyright (C) 2016-2017 Oliver Heimlich
Copyright (C) 2017 LoVullo Associates, Inc.
This file is part of Octave.
@ -110,3 +111,36 @@ but don't sacrifice space on small screens.
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;
}

View File

@ -10,7 +10,12 @@
@c Free Documentation License''.
@c %**start of header
@include config.texi
@include version.texi
@include macros.texi
@c Developer Notes index (used only if DEVNOTES)
@defindex dn
@setfilename liza.info
@settitle Liza Data Collection Framework v@value{VERSION}
@ -47,6 +52,12 @@ Free Documentation License''.
@insertcopying
@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
@ifnottex
@ -57,6 +68,9 @@ Free Documentation License''.
@menu
* Design and Architecture:Design. Design and structure of framework
* Concept Index::
@ifset DEVNOTES
* Developer Notes Index:: Index of pertenant notes for developers of Liza.
@end ifset
@end menu
@ifnottex
@ -64,11 +78,17 @@ Free Documentation License''.
@insertcopying
@end ifnottex
@include macros.texi
@include design.texi
@node Concept Index
@unnumbered Concept Index
@printindex cp
@ifset DEVNOTES
@node Developer Notes Index
@unnumbered Developer Notes Index
@printindex dn
@end ifset
@bye

View File

@ -8,22 +8,88 @@
@c Texts. A copy of the license is included in the section entitled ``GNU
@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
@macro mdash{}
@macro mdash
@inlinefmtifelse{html, @inlineraw{html,—}, }
@end macro
@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
@macro helpwanted{}
@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