Hello again, it appears that it may be hard to follow what this is all about, so let me elaborate a bit on the why the work is necessary and what the solution looks like.
The current LaTeX class in SDAPS has been designed with only one use
case in mind. This use case is to create simple anonymous surveys.
Because of this the class has numerous assumptions and shortcomings.
For the use case of more complex surveys some new layout options and
question types are required. These are for example
* a better range question with fields that are not part of the range,
* array layouts where the questions are in columns instead of rows,
* and specifying the variable name and values for the data export.
Looking at what some people are doing with examinations there are even
more complicated layouts required. Due to this and the fact that the
style of the SDAPS class cannot be easily modified some people have
started to only use the small base feature set of the SDAPS class and
manually specify all the metadata instead of relying on what SDAPS
provides. For these users the class pretty much only provides very basic
functionality to draw text and checkboxes with known coordinates.
A further usecase that exists in exams is that one might want to put
some content inside a textbox for the exam itself. And it is also
necessary to create a sample solution. Both of these features require a
good way of rendering content inside normal textboxes and checkboxes.
SDAPS does not currently provide any infrastructure for this.
Last but not least, some people would like to see support for PDF forms,
which is a very similar problem in the sense that it requires overlaying
PDF form elements on top of the normal SDAPS boxes.
Solution
--------
I have made the decision that there is no point in keeping the current
class, instead a complete redesign is required. By doing this redesign
all of the points that are mentioned above can be taken into account,
and many more new and nifty features are possible.
Note that this will break compatibility, and my current plan is to
release SDAPS 2.0 with the new class and new features.
The idea with the new class is to cater both to novice users while
allowing complicated use cases. So SDAPS will still provide a simple
interface similar to the current one while at the same time allowing to
drop down to use the very advanced features that are available in the
new "sdapsbase" core package..
As the development has started with the core support package, there is
currently no "simple" code that is useful for most end users. However a
lot of work has gone into creating an abstraction layer and powerful box
drawing functionality and this has already stabilized a lot.
Lets elaborate on some of the features and a bit on the implementation …
Overlays
--------
For all SDAPS fields (checkboxes, textboxes) we want the ability to
overlay/fill them in different ways. This is absolutely necessary to
create sample solutions for examinations, and will also be useful in
other scenarios like creating PDF forms.
Unfortunately supporting this requires quite a large infrastructure in
the backend. Consider array layouts, where the user specifies a number
of questions and a set of answers for each of these questions (see New
Layout Options further down for an example). In that case SDAPS
generates all the checkboxes internally, which makes it impossible to
directly specify overlays in the LaTeX file. This means we need an out
of band way to predefine the overlay so that SDAPS can lookup the
information on the fly.
The solution to this problem is two fold. The first part is to
dynamically build a name for each checkbox in an hierarchical fashion.
This variable name (it is later used in the CSV export for the
checkboxes data) in combination with a value (in the case of range
questions) uniquely identifies every single checkbox. The second part is
then to use the variable name and value to dynamically change the
configuration for each checkbox.
So if you wanted to create a sample solution you can now do something
like the following (this already works!):
\sdaps_overrides_init:n {
*={
my_variable_1={
centered_text=O,
},
another_variable={
centered_text=X,
},
range_variable&8={ % 8 is the value
centered_text=X,
},
},
}
The first * is actually a wildcard for the questionnaire ID. So you
could even create a set of unique questionnaires and pre-fill them
differently if you want to. The last entry shows that you can specify
either just a name or a name/variable combination that is separated by a
& character.
Context
-------
Another new concept is that the base configuration for checkboxes is
done in a context system. This system allows modifying the settings for
only a part of the document. A very simple example is that questions
where only a single answer is allowed should have rounded checkboxes,
while multiple choice questions should use square boxes. So you have to
change the checkbox to be rounded for the context of a single question.
This context also allows to change all other parameters of checkboxes
(e.g. add overlays, turn on PDF form generation, ...).
The more experienced LaTeX user might ask why SDAPS has a custom context
implementation instead of just using the LaTeX normal LaTeX grouping
mechanism. The reason for this is rather simple, a system based on LaTeX
groups would not be independent of the groupings used by the layout
code. So you couldn't for example start a context inside a multicolumn
environment, but end it somewhere outside of it.
Note that this API is *only* required when creating custom classes or
very complex layouts. Most users will never see it.
Some new commands:
* \sdaps_context_begin:n { NAME }
* \sdaps_context_end:n { NAME }
unnamed variants, the name is to catch errors/pop multiple contexts at
the same time:
* \sdaps_context_begin:
* \sdaps_context_end:
And one that automatically ends when the current TeX group ends:
* \sdaps_context_begin_local:
Modification and access API:
* \sdaps_context_put:nn Sets a value
* \sdaps_context_set:n Sets multiple values in the form key=value,...
* \sdaps_context_append:nn Appends to a value
* \sdaps_context_clear: Clear everything
* \sdaps_context_map:N Iterates over all options
PDF Forms
---------
With the infrastructure in place to create new overlays, it becomes
pretty simple to implement a PDF form feature inside SDAPS. This
implementation is inside a separate sdapsform package, which simply adds
two new overlays and some configuration options.
So creating a PDF form with the new class just requires three steps
right now:
1. load the sdapsform package
2. wrap the whole document inside a \begin{Form}/\end{Form}
3. Modify the context so that form elements are created:
\sdaps_context_append:nn{*} {pdf_form=true}
That is all there is to it. And you can also pre-select items, etc.
using the override feature. Once there is a standard SDAPS class to use
the requirement to manually add a \begin{Form}/\end{Form} might even
disappear. The third step will probably change slightly as it requires
enabling the LateX 3 syntax right now, which is pretty inconvenient.
New Layout Options
------------------
The above mentioned infrastructure is pretty working now, so the next
step is to create the next layer on top. This next layout is the
"sdapslayout" package which will provide standard question layout code.
Right now the only implemented feature is the array layout for which
Henry contributed the code. It allows specifying a set of questions that
all have the same choices as answers.
Lets just show a very small example:
\begin{choicearray}[var=group,horizontal]{A group of questions}
\choice[var=latex,text=LaTeX]{\LaTeX}
\choice[var=opt2]{Option 2}
\choice[var=opt3]{Option 3}
\question[var=q1]{Question 1}
\question[var=q2]{Question 2}
\end{choicearray}
This will result in something like:
\LaTeX Option 2 Option 3
Question 1 O O O
Question 2 O O O
Where the variables are:
group_q1_latex group_q1_opt2 group_q1_opt3
group_q2_latex group_q2_opt2 group_q2_opt3
By simply changing "horizontal" option to "vertical" you get instead:
Question 1 Question 2
\LaTeX O O
Option 2 O O
Option 3 O O
I think this is a pretty neat feature, as you can properly describe the
question itself, and then simply change the layout to suit your need.
Though this is feature still needs a lot of improvement and fine
tweaking. I could imaging the following features for example:
* optionally rotate labels at the top
* Insert freeform textboxes
* different column sizing options
Oh, the attentive reader might have noticed the text=LaTeX parameter.
This modifies the metadata output so that instead of writing "\LaTeX"
the replacement text "LaTeX" is written. This way any special formatting
can be hidden which might be important for report generation of further
data processing.
Conclusion
==========
So with this we are on the way to get some great new features into
SDAPS. There is still quite a lot of work until we have a nice high
level SDAPS class that can be used to quickly create a survey. That
said, the core is working just fine.
Most work that is left right now is implementing a base set of question
types to make it all easy to use and then fine tuning their layout so it
all looks great by default. Then it just needs to be wrapped into an
easy to use class which should be relatively straight forward.
I hope that this better explains some of the aspects and thoughts behind
the whole LaTeX class rewrite that is happening. That said, don't
hesitate to bring up any questions you have, I am happy to answer them
all.
If you are interested to push this forward, I would of course appreciate
any help, be it in the form of code contributions or comments about the
current design.
And even just a small heads up would be nice to keep me motivated to
work on it :)
Thanks for reading!
Benjamin
On So, 2015-04-12 at 21:00 +0200, Benjamin Berg wrote:
> Hey,
>
> so, I finally got around to integrate Henrys work and add some much
> needed improvements to the base package. See attachment for a very
> simple but already pretty cool example of what is possible with the new
> package (and in theory it should work just fine with the "variables"
> branch of SDAPS, except that the "DRAFT" overlay does not disappear
> right now).
>
> See the attachments. The following is new/notable:
> * The only difference between the two sections is the change of
> the horizontal/vertical flag.
> * Variables in the form tool_letter_latex are generated. The
> second environment has a manual prefix of 2_ set to avoid
> collisions.
> * Two fields are pre-selected by variable name (see
> questionnaire.sdaps file)
> * It is all PDF forms (not really new).
>
> Not shown are text fields, but these still work fine in general.
>
> Next steps:
> * More layout options (especially all the old ones).
> * Support for inline text fields in the array environment.
> * A wrapper class that defines a nice style.
> * Probably some cleanups in the base package (e.g. I am not
> entirely happy with the current writepos flag).
>
>
> I should probably give some in depth explanations in a follow up mail of
> how the context management and overrides work. It is a bit of a
> class/instance thing really, where the context modifies the classes
> defaults (e.g. */checkbox/textbox where * is wildcard) and the override
> mechanism addresses single checkbox OR textbox instances based on the
> variable name or value.
>
> As always, everything is already on github. I would appreciate any
> comments on the work so far or even a review of the base package!
>
> Benjamin
>
> On Do, 2015-01-22 at 17:24 +0100, Benjamin Berg wrote:
> > Hi,
> >
> > I have recently done some development on a new LaTeX packages and
> > classes. There has also been work in different areas (thanks to Henry
> > Menke). So far I have focused on the low level infrastructure for
> > typsetting text- and checkboxes, while Henry contributed mechanisms for
> > complex question layouts (not yet included).
> >
> > The new code is available at http://github.com/sdaps/sdaps-class for
> > now. Internally it uses LaTeX 3 (which is really nice). If you like to
> > test it grab the source and run "make". This will build sdapsbase.sty,
> > the documentation (incomplete) and the test document.
> >
> > In the new code the general layout infrastructure will be split from the
> > question layout and main class. This will make it a lot easier to create
> > custom layouts or even create a custom class for SDAPS.
> >
> > Cool new stuff:
> > * Overlays! You can overlay anything on top of checkboxes and
> > textboxes. Included overlays will be PDF forms, custom text,
> > checkbox drawing, ...
> > * A flag management system. You could pre-fill a (PDF) form using
> > the Questionnaire-ID for example.
> > * Place a textbox around a normal LaTeX horizontal or vertical
> > box.
> > * More robust vertical stretching
> > * A context management system to manage hierarchy (think about
> > matrix layouts, sections, ...)
> >
> > It is all still in a very early development stage, and some parts will
> > likely require redesigns. A lot of things are not even hooked up
> > correctly internally yet (e.g. textboxes are not configurable).
> >
> > Note that it probably only makes sense to look at this if you are
> > interested in layout issues and package/class development itself. The
> > user visible interface is not yet in a state where it can be reviewed
> > properly.
> >
> > Benjamin
> >
> > PS: My test document: http://sdaps.org/misc/latex3-test.pdf
> > * checkboxes modified based on Questionnaire-ID and name (top)
> > * Different checkbox overlays enabled, including PDF forms
> > * Textboxes placed around text ("coffin" is the LaTeX3 construct used)
> > * scaling textboxes (pages 2 and 3 show some layout scenarios)
>
signature.asc
Description: This is a digitally signed message part
