Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.soft-sys.math.mathematica > #3457 > unrolled thread

Re: How to write a "proper" math document

Back to article view | Back to comp.soft-sys.math.mathematica

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: How to write a "proper" math document "McHale, Paul" <Paul.McHale@excelitas.com> - 2011-07-03 08:13 +0000
    Re: How to write a "proper" math document Richard Fateman <fateman@cs.berkeley.edu> - 2011-07-04 10:46 +0000
    Re: How to write a "proper" math document Chris Degnen <degnen@cwgsy.net> - 2011-07-06 09:40 +0000
    Re: How to write a "proper" math document "McHale, Paul" <Paul.McHale@excelitas.com> - 2011-07-07 11:44 +0000

#3457 — Re: How to write a "proper" math document

Daniel,

I couldn't agree more.  We are struggling with the best way to document.  Pasting into Word works, but is a secondary effort, as you said.  I think there are two levels of writing for engineering.  The first level is documenting what one has done or will do.  The intent is little deviation once written.  Unfortunately there is no increase in innovation by this process.

I think it is better being able to learn something from writing the documentation.  This is very difficult to teach.  I believe Mathematica not only supports this but is one of very packages that will even come close to preventing the duplication of effort you mention when creating documents.  The engineer must be able to experiment with models and math before implementation.

I think two advancements are required.  We, as engineers, need to accept the correlation between experimental writing and innovation.  Too many treat the actual development as the "playground" or sandbox to experiment.  I think this is prohibitively expensive.  Changing documentation is cheap compared to circuit cards or distributing software.  Experimenting in documentation is much faster.  Care must be taken as models are always incomplete.  Of course, so are first design efforts :).  I'm also of the school that proper engineering starts with documentation.  The actual implementation should be reduced to recipe.  First design reviews should be of documentation where changes are "free".  Unfortunately, the artistic/emotional side of engineers find this physically painful. 

It would be very helpful if IEEE or some other body would start a set of standards for documenting engineering work.  CMMI was interesting but enforces no definition of a specific process.  I think engineers are untrained/unskilled in this area and could use some standards.

The second part is Mathematica needs to flow back and forth better between document (read mode for others) and development (all code visible...).  This is especially true for people who don't know Mathematica.  They will get lost seeing all the unfamiliar code.  I find going from working with code to putting a document in presentation or readable form (hiding the code) is a lot of effort.  Closing and opening code segments is too much of an effort.  It would be nice to have two sets of properties, one for working mode and the other for reading mode.  Just me 2c.

Paul

Paul McHale  |  Electrical Engineer, Energetics Systems  |  Excelitas Technologies Corp.

Phone:   +1 937.865.3004   |   Fax:  +1 937.865.5170   |   Mobile:   +1 937.371.2828
1100 Vanguard Blvd, Miamisburg, Ohio 45342-0312 USA
Paul.McHale@Excelitas.com
www.excelitas.com



Please consider the environment before printing this e-mail.
This email message and any attachments are confidential and proprietary to Excelitas Technologies Corp. If you are not the intended recipient of this message, please inform the sender by replying to this email or sending a message to the sender and destroy the message and any attachments.
Thank you

-----Original Message-----
From: dr DanW [mailto:dmaxwarren@gmail.com]
Sent: Saturday, July 02, 2011 5:03 AM
Subject: Re: How to write a "proper" math document

Mathematica is probably the best environment for what Donald Knuth would term Literate Mathematics or Engineering.  It allows comments in rich text and typeset mathematics in the same document as functional code, data, live plots, and now interactive demos.  The only other product that comes close uses another M product with LaTeX, but Mathematica has the edge over that one with the interactive demos.

This is important to me as the director of a research department.  I am trying to find ways to get my engineers to document their work.  As long as writing documentation is a separate operation from doing work (calculations, data crunching) it will always take the back seat.  However, if documenting is concurrent with working I don't have to tell anybody to go back and finish the job.

Daniel

[toc] | [next] | [standalone]

#3470

It is quite simply the case that any system which requires a reader or 
writer of a document to pay WRI an annual license will be rejected by 
the vast majority of people, as well as any journal published by a 
reputable academic/ scientific non-profit organization such as IEEE, 
AMA, ACM.

It appears that Mathplayer (etc) don't do the job for what you are 
talking about.

There are several competing products in this active-math document 
editing framework, including web-page based products which allow (they 
claim) easy call-outs to programs and programming languages without 
going through Mathematica, Mathlink, etc.

Mathematica is hardly the first language of choice for most of the 
world, and in spite of what you may think of its graphical, interactive, 
animation (whatever) is hardly unique.

I would add (though clearly others have expressed disagreement on this 
point) that embedding Mathematica semantics in numerical and some 
symbolic computations would be a grave disservice to actual scientific 
calculations.  Consider the situation when the most important 
characteristics of a formula are those locations where it is singular, 
but Mathematica leaves them out because they are not part of the 
"generic" solution.  Or the numerical computation which should be done 
to higher precision, but Mathematica displays the answer as 0. 
Neglecting to mention that it really could be anything at all, just that 
it has apparently lost all significance.

I am generally in favor of the notion that engineering or other 
scientific/mathematical journal articles or documentation should include 
material that can be cut out and pasted elsewhere, including in a 
computer algebra system.  Or having them be "clickable".

One way of doing this is via what is sometimes called "multivalent" 
documents.  See
http://www.eecs.berkeley.edu/Pubs/TechRpts/1998/CSD-98-999.pdf

If you look at this (circa 1998) paper, you will see that it shows, in 
principle, how one can take an existing document that includes math 
expressions, and via OCR and some help, present an additional layer to 
the reader that provides active computation or extraction into TeX.

Constructing a paper initially in digital form removes the need for OCR, 
but the multiple-layer notion seems like a good one.  Whether you 
consider that Mathematica provides all you need now or not, do you think 
that a document prepared with version 8.0 will still "work" in a later 
version?  Will you be able to effortlessly attach a layer of 
annotations, corrections, 3D-smell-o-vision, etc. in the future? Will 
you have layers of historical versions of the past?  Will you be able to 
send it to a colleague who does not have a license?

RJF

[toc] | [prev] | [next] | [standalone]

#3513

On Jul 3, 9:13 am, "McHale, Paul" <Paul.McH...@excelitas.com> wrote:
> Daniel,
>
> I couldn't agree more.  We are struggling with the best way to
> document.  Pasting into Word works, but is a secondary effort,
> as you said.  ...


I plan to automate output to Word to create editable documents.

As an example of what can be done in .Net from Mathematica, the
ExcelPieChart.nb demo is very interesting...

See "Calling COM Objects" on this page, (first section):

http://reference.wolfram.com/mathematica/NETLink/tutorial/CallingNETFromMathematica.html

I have obtained the textbook Writing Word Macros, which gives
VBA examples for manipulating the Word object model, but if there
is any reference material or examples of the Mathematica syntax
for manipulating Word I would be interested to know of it.  Thanks

[toc] | [prev] | [next] | [standalone]

#3552

-----Original Message-----
From: Chris Degnen [mailto:degnen@cwgsy.net]
Sent: Wednesday, July 06, 2011 5:41 AM
Subject: Re: How to write a "proper" math document

>I plan to automate output to Word to create editable documents.
>
>As an example of what can be done in .Net from Mathematica, the
>ExcelPieChart.nb demo is very interesting...
>
>See "Calling COM Objects" on this page, (first section):
>
>http://reference.wolfram.com/mathematica/NETLink/tutorial/CallingNETFromMathematica.html
>
>I have obtained the textbook Writing Word Macros, which gives
>VBA examples for manipulating the Word object model, but if there
>is any reference material or examples of the Mathematica syntax
>for manipulating Word I would be interested to know of it.  Thanks

Be advised we had a legacy system based on VB macros.  Every time Windows updates or office updates, the macros break.  There must be a way around this.  We have yet to find it.

Paul

[toc] | [prev] | [standalone]

Back to top | Article view | comp.soft-sys.math.mathematica

csiph-web