gaf: add a feature to change scale factor

[Vladimir Zhbanov]

The new 'gaf' tool can export schematics in various formats. One
of missing things is output using predefined fixed scale factor,
which is desirable in some cases. For example, some Russian state
standards order to use definite sizes for schematic title frames.
Another example is creating illustrations for a book where
you want to have a known definite scale for all your symbols.

The attached patch adds such a feature.
(It is for the current master head 74515e).

[Peter TB Brett (peter-b)]

Some comments about this patch.

1) I like the idea of using ':' as a separator for the options that take multiple arguments, and I can't believe I didn't think about it myself! Would you like to submit a patch to make -m and -s accept it as a separator, and also to update the manpage to show it as the recommended separator? :-)

2) I really *don't* like the --scale=IN:OUT syntax. I find it extremely confusing, and I really don't understand how it works or when it would be useful, even from reading the manpage! I strongly suggest only allowing --scale=FACTOR; I think it would make the --scale feature much easier to understand without any actual loss of functionality.

3) When mentioning metasyntactic variables in the explanation of a command-line option, please put them in italics. For example:

-Scale the output according to a specified scale factor. If one number is
+Scale the output according to a specified scale \fIFACTOR\fR. If one number is

-be equal to OUTPUT_UNIT/INPUT_UNIT.
+be equal to \fIOUTPUT_UNIT\fR/\fIINPUT_UNIT\fR.

Thanks!

[Vladimir Zhbanov (vzhbanov)]

> 1) I like the idea of using ':' as a separator for the options
> that take multiple arguments, and I can't believe I didn't think
> about it myself! Would you like to submit a patch to make -m and
> -s accept it as a separator, and also to update the manpage to
> show it as the recommended separator? :-)

As for -s and -m option arguments (as well as -a), I'd prefer
using commas between values since they actually form a list. They
are not so much tied together as the --scale option arguments
(which I'll try to make clear below).

> 2) I really *don't* like the --scale=IN:OUT syntax. I find it
> extremely confusing, and I really don't understand how it works
> or when it would be useful, even from reading the manpage! I
> strongly suggest only allowing --scale=FACTOR; I think it would
> make the --scale feature much easier to understand without any
> actual loss of functionality.

To me, what the current patch certainly lacks now is a more
detailed documentation :) OK, I'll try to make my point more
clear.

As I already said, there is a standard which specifies title sizes
for various Russian titles. I know that some people have already
made metric (A4, A3...) titles using different scales. One of them
is at gedasymbols.org. It is some larger than mine and I think it
scales 100 gschem points to 4 mm when printed. I read somewhere
that another person have made his title so that 100 gschem points
represent 1 mm. Personally I prefer to use default library
symbols sometimes (if only temporarily), so I set up my printing
scale so that 100 gschem points is equal to 2.5 mm (which is close
to 0.1in).

So, for the reason not to break historically developed user
workflows, I propose an intuitive way (from my point of view) to
set the scale for printing using the form like "0,1in:1mm",
"0,1in:4mm", or "1in:25mm" (where comma substitutes for decimal
point in my locale). It is similar to what is used for
geographical maps and that is why I've chosen it. And such a
scaling was the main goal of that patch. The prerequisite for this
is the fact that gaf internally considers 1 gschem point to be
equal to 1 mil. If not such an assumption (which I consider being
wrong), I'd propose another way: add an explicit measure unit
setting for export which could be 1 mil by default (and use it for
gschem, too).

> 3) When mentioning metasyntactic variables in the explanation of
> a command-line option, please put them in italics. For example:
> ...

OK, thanks.

[Peter TB Brett (peter-b)]

> As for -s and -m option arguments (as well as -a), I'd prefer
> using commas between values since they actually form a list. They
> are not so much tied together as the --scale option arguments
> (which I'll try to make clear below).

Unfortunately, using a comma as a separator just won't work. As you mentioned below:

> comma substitutes for decimal point in my locale

In such a locale, "--margins=0,3cm,0,4mm" cannot be parsed consistently if a comma is permitted as a field separator for --margins, because it could either mean --margins="0 3cm 0 4mm" or --margins="0,3cm 0,4mm". So I'm sorry, but we cannot use ',' as a field separator for --size or --margins. Using ';' is also problematic, because if it's not quoted then /bin/sh interprets it as end-of-command. So I think that using ':' is probably the best option... :-/ WDYT?

> [snip]

Okay, I understand better now! Really, gschem units could be considered arbitrary -- they don't strictly need to be interpreted as 0.001 in, it's just a "legacy" interpretation. How about this: have "--scale=FACTOR", where FACTOR is the real-world distance that one gschem unit corresponds to. (And then "--size=auto" is equivalent to "--scale=0.001in"). Is that what your proposed "another way" was? I think it might be easier to understand/explain.

In the long run, I would like gschem's "Write image..." function to call out to gaf export. But that depends on bug 1085990.

Thanks again for working on this!

[Vladimir Zhbanov (vzhbanov)]

Agreed with ":".

And yes, my "another way" means explicit gschem printing unit
setting.

What do you think of changing '--scale' to more intuitive '--unit'
then (and the short options would be '-u')?

And what if the unit would be equal to 100 gschem grid points (100
mils instead 1 by default). It would let users enter values as 2.5mm
rather than 0.025mm. Of course, this will require some explaining
in the doc.

[Peter TB Brett (peter-b)]

Great, I think we're approaching a solution!

I think we should stick with "-k, --scale"; I'm worried that "--unit" or "--units" might confuse people (for example it could be misinterpreted as setting the default unit for "--margins" or "--size" for example).

And making it 100 gschem grid units rather than 1 is a very good idea. I will leave writing the documentation in your capable hands (although I'm very happy to offer help if you would like it, since I know English is not your first language).

[Peter TB Brett (peter-b)]

These are much better patches! I have a few small niggles:

1) Please write \fBgschem\fR(1) so that man viewers automatically turn it into a link.

2) The first patch contains an unrelated change to a comment in libgeda.

3) In the second patch, I meant that we should *add* ':' as a separator (so "; " --> ":; " in the g_strsplitset() calls).

If you can quickly fix those, then I will happily merge this ASAP. :-)

[DJ Delorie (djdelorie)]

We've always resisted the urge to make gschem units mean physical
units, so "mm" would be "wrong".

I also suspect that using any unit other than gschem's natural unit
would only cause confusion.

Perhaps a percentage would be suitable, to scale text relative to what
you "normally" get? That way you could compensate for font choices,
without overriding the ability to have various sized texts on your
schematics.

[Peter TB Brett (peter-b)]

This patch doesn't add any interpretation for gchem units. It does, however, provide a way for users to supply their own preferred interpretation. Also, this has nothing whatsoever to do with fonts or text.

[gpleda.org commit robot (gpleda-launchpad-robot)]

A commit was made which affects this bug
git master commit 574e50602151f2584487c535d857e94a1ccb6e1e
http://git.geda-project.org/geda-gaf/commit/?id=574e50602151f2584487c535d857e94a1ccb6e1e

commit 574e50602151f2584487c535d857e94a1ccb6e1e
Author: Vladimir Zhbanov <email address hidden>
Commit: Peter TB Brett <email address hidden>

    gaf: add ":" to the list of option arguments separator

    The reason for such a change is the fact that the separator ";"
    is used by shell and should always be quoted for proper operation.

    Affects-bug: lp-1086522

[gpleda.org commit robot (gpleda-launchpad-robot)]

Bug was fixed by a commit
git master commit 345f64cfbc30caf29a812954928311daac3a0646
http://git.geda-project.org/geda-gaf/commit/?id=345f64cfbc30caf29a812954928311daac3a0646

commit 345f64cfbc30caf29a812954928311daac3a0646
Author: Vladimir Zhbanov <email address hidden>
Commit: Peter TB Brett <email address hidden>

    gaf: added the --scale option

    This option lets users to set a known scale for their titles and symbols
    when they have to. It can be used, for instance, to keep the same known
    scale for several schematics or ensure the conformity with standards
    requiring using definite sizes for titles (e.g. Russian GOST).
    The argument of the --scale option should be given as the output size
    corresponding to 100 points in gschem (one default grid spacing), i.e.
    100 mils by default.

    Closes-bug: lp-1086522