Add tool to extract LaTeX-formatted text from comments in Dart programs

Add tool to extract LaTeX-formatted text from comments in Dart programs

R=zhivkag@google.com

Committed: https://github.com/dart-lang/sdk/commit/60be18b4a9d68116bfa1fc5adeac7167a5816287

[Dmitry Stefantsov, 2017-05-17 11:59:21]

dmitryas@google.com changed reviewers:
+ kmillikin@google.com, zhivkag@google.com

[Dmitry Stefantsov, 2017-05-17 11:59:21]

I've written a simple tool that allows us to write LaTeX code right in the
comments in Dart.

I believe it may help us to follow design-first approach with the interpreter,
when we may first write methods with empty bodies and write the appropriate
comments describing CEK machine transitions, and then fill in the method bodies.

Also, we may now have discussions about the design in the code review tool.
Maybe it will allow us to avoid duplicating our design decisions in multiple
places, like wiki, google docs, etc.

To illustrate how the tool works, I put some LaTeX comments into the extractor
file itself.

This is a tool written in a hurry, it may have been written better :)

[zhivkag, 2017-05-18 08:25:20]

Thanks for writing this, Dima! LGTM

I would suggest having some of the LaTeX metadata either in the tool itself or a
separate document specific for the interpreter documentation, since it does/will
not depend on the implementation. 

I think it would be nice to have only the documentation for the CEK machine
transitions in the interpeter.dart, and the suggestion above is one way of
solving that.

[Dmitry Stefantsov, 2017-05-18 08:36:56]

On 2017/05/18 08:25:20, zhivkag wrote:
> Thanks for writing this, Dima! LGTM
> 
> I would suggest having some of the LaTeX metadata either in the tool itself or
a
> separate document specific for the interpreter documentation, since it
does/will
> not depend on the implementation. 
> 
> I think it would be nice to have only the documentation for the CEK machine
> transitions in the interpeter.dart, and the suggestion above is one way of
> solving that.

Sure, we may have the metadata in a separate file. Actually, LaTeX has \input
command that we may use to include the contents of other file directly into our
file. We may do this in one of the two ways: (1) write a file with the metadata,
and include the .tex file generated by the tool into it, or (2) use the \input
command in the comments of the .dart file to include all the metadata.

Hope, that tool will be useful :)

[Dmitry Stefantsov, 2017-05-18 08:48:38]

Description was changed from

==========
Add tool to extract LaTeX-formatted text from comments in Dart programs
==========

to

==========
Add tool to extract LaTeX-formatted text from comments in Dart programs

R=zhivkag@google.com

Committed:
https://github.com/dart-lang/sdk/commit/60be18b4a9d68116bfa1fc5adeac7167a5816287
==========

[Dmitry Stefantsov, 2017-05-18 08:48:40]

Committed patchset #1 (id:1) manually as
60be18b4a9d68116bfa1fc5adeac7167a5816287 (presubmit successful).