Difference between revisions of "ICalico Development 2014 BMC"

From IPRE Wiki
Jump to: navigation, search
(Thursday, July 3, 2014)
(Tuesday, July 15th, 2014)
 
(55 intermediate revisions by 3 users not shown)
Line 66: Line 66:
 
ICalico documentation:
 
ICalico documentation:
  
* [ICalico] - the only docs we have so far
+
* [[ICalico]] - the only docs we have so far
 +
 
 +
 
 +
Mattie's Wishlist: 
 +
* Being able to make the lines of tables invisible
 +
* Being able to have reference-style links be defined in any cell in the notebook
 +
 
 +
== Monday, July 7th, 2014 ==
 +
 
 +
Goals for the week:
 +
 
 +
* JavaScript:
 +
** Number Sections
 +
*** Completed July 7th. Has not been tested extensively. Code is located in "Labeling Headers" notebook on Dropbox.
 +
** RenameLinks
 +
*JavaScript:
 +
** Table of Contents
 +
*** JavaScript Hints:
 +
**** https://github.com/minrk/ipython_extensions/blob/master/nbextensions/toc.js
 +
**** https://github.com/ipython/ipython/tree/master/IPython/html/static/notebook/js - IPython Javascript, see notebook.js and cell.js
 +
** Remove Old One?
 +
* Timeline
 +
**JSON
 +
**Documentation
 +
 
 +
== Tuesday, July 8th, 2014 ==
 +
 
 +
Testing and added functionality of automatic section numbering:
 +
 
 +
* Discussed several new features with Mattie to make section numbering more user-friendly, including:
 +
** Added alerts that warn user when missing intermediate headers
 +
** Added additional alerts warning users when the first header cell in their Notebook is not a Header 1 cell
 +
** Determining when parts of certain user-defined titles should/should not be replaced
 +
* Tested more extensively, removing several bugs with replacing already existing headers
 +
** Users cannot name sections of their notebook titles that match the defined section numbering pattern (i.e. naming a section "1.5 Pies" will delete '1.5' and replace it with the correct section number for that section, even if '1.5' was intended to be part of the title)
 +
* Successfully generated section numbering for Mattie's Reference Guide
 +
 
 +
 
 +
Completed Raw Implementation of Table of Contents Generator:
 +
 
 +
* Code is labeled "Table of Contents Code" on Dropbox
 +
* Mostly working with few bugs
 +
* Several design questions that can be discussed in the future
 +
* Put a new copy of the reference guide (Title: "Reference Guide Plus Code") in the Dropbox folder which demonstrates both Section Numbering and Table of Contents Generation!
 +
Known Bugs:
 +
* Making a markdown link that contains ")?)" forms some sort of escape and will not link properly. Cause unknown. '''EDIT:''' Fixed 7/9/2014
 +
 
 +
 
 +
Doc Writing Update (from Mattie):
 +
 
 +
*Finished explanation of toolbar, with exception to the restart kernel tool and the cell toolbar drop down menu, both of which I am trying to figure out the function of
 +
*Fix internal links so that they don't open up a new window (with Cole's help)
 +
*Introduced several new sections to the whole guide, including one that hopefully will link to Cole's automatic section numbering program
 +
*Currently trying to write a section on how to turn your Notebook into a slideshow, but I'm still figuring out how to do it for myself.
 +
 
 +
== Wednesday, July 9th, 2014 ==
 +
 
 +
Bug Fixes:
 +
 
 +
* Added a fix to remove trailing spaces from links for the table of contents generator
 +
* Added a fix to replace all parentheses with their encodings (%28 and %29 respectively) fixing the bug causing links with parentheses to render incorrectly.
 +
 
 +
 
 +
Potential New Bugs For Discussion:
 +
 
 +
* Unordered lists do not render if the indentation level increases by more than one tab at a time. Notebooks with headers that are inconsistent in this way (i.e. jumping from header 1 to header 3) will not render their table of contents correctly. However, this could warn users of potential errors within their notebook.
 +
 
 +
 
 +
Timeline Work:
 +
 
 +
* Initial documentation (including JSON file format) - https://github.com/NUKnightLab/TimelineJS
 +
* Example JSON file - https://github.com/NUKnightLab/TimelineJS/blob/master/examples/example_json.json
 +
 
 +
== Thursday, July 10th, 2014 ==
 +
 
 +
Doc Writing Update (From Mattie)
 +
*After trying to figure out how to view my notebook as a slide show, getting very confused in the process, and asking both Ian and Cole for help, I have determined that there currently is no super easy, intuitive way to do this. Ian set it up so it's not too hard, but it does require entering bash commands in terminal. I'm not sure it makes sense to document this process right now, because hopefully we can change it to be more user/novice user-friendly.
 +
** '''Doug: As you have found, normally, nbconvert is run on the notebook from the command-line. But I just saw that someone made it so that you can do a slideshow from inside a live notebook by pressing a button. I'll see if I can find that... Here it is:'''
 +
*** https://github.com/damianavila/live_reveal
 +
*** https://www.youtube.com/watch?v=Pc-1FS0l2vg
 +
*Similarly, I am interested in talking about Cole's useful table of contents and section numbering code, but I don't know how it will eventually be implemented for any given user, so I'm holding off on procedural documentation for that function as well.
 +
** '''Doug: We'll put those options (Table of Contents and Heading Numbering) on the menu in the notebook.'''
 +
*Also, Cole did me a favor and wrote a very simple find and replace code that I think could be turned into a useful tool for humanities and social science students writing papers. In my case, it just replaced every instance of the phrase "IP[y]" and replaced it with "Jupyter".
 +
**'''Doug: not sure if we can write a find-and-replace version that will be good enough to be used.'''
 +
*I've finished the section on Keyboard short cuts, though right now it just directs the user to the help menu. I wasn't sure reduplicating the a legend for all the keyboard short cuts directly into a cell of the reference guide notebook would be that helpful, but I can do that if it does turn out to prove worthwhile.
 +
 
 +
 
 +
Timeline Updates:
 +
 
 +
* Have figured out the correct format for JSON data in order to render a timeline using a file instead of googledocs
 +
* Current embedding code breaks a notebook when run, rendering it useless:
 +
** All functionality is lost, including keyboard shortcuts, backspacing already written text, etc.
 +
** <nowiki><div></nowiki> tags seem to function fine otherwise so something about the scripts being run seems to be the problem
 +
* I've tried several different methods of embedding this code, including the two methods listed in the timelineJS documentation, and using python to call the HTML display functions
 +
* Generating proper JSON format from a markdown table should be fairly easy as the format is basically straightforward
 +
 
 +
== Friday, July 11th, 2014 ==
 +
 
 +
Mattie and I had quite a long discussion about referencing support today (3+ hours). Summary is below:
 +
 
 +
Bibliography Support:
 +
 
 +
* What style do we use? What style is useful?
 +
** Footnotes
 +
*** Doesn't really make much sense in a notebook
 +
*** Most useful style
 +
** Scientific ([1]) Linking
 +
*** Easy to implement
 +
*** Not as useful in humanities
 +
** MLA
 +
*** Easy to implement
 +
*** Useful, but doesn't really require much support
 +
 
 +
* What sort of interface do we want?
 +
** Markdown cell with reference information
 +
*** Pros:
 +
**** Store all your bib info easily in one document.
 +
**** Automatic citation generation and ordering
 +
*** Cons:
 +
**** Cell will get rendered (Possible fix with html commenting)
 +
**** Formatting might be difficult (Tag cell with %bib or something similar)
 +
** Separate notebook
 +
*** Pros:
 +
**** Very organized
 +
**** Formatting is easy to define and accessing isn't hard
 +
*** Cons:
 +
**** Not all in same notebook
 +
**** Non-computer scientists might find this format/organization more difficult
 +
 
 +
* Extra Ideas:
 +
** Tagging feature for organizing thoughts during pre-writing/planning
 +
** Tags are just HTML comments. Could include page number and will stay once everything is rendered, but not appear in rendered cell.
 +
** Mouse-over titles are full citation
 +
 
 +
== Monday, July 14th, 2014 ==
 +
 
 +
Goals for the next three weeks:
 +
 
 +
* Polishing:
 +
** Section Labeling
 +
*** Simplicity
 +
*** 1 Warning at end
 +
*** Ask about header cells. Dealing with headers in markdown
 +
*** Add to menu
 +
** TOC
 +
*** Dummy Levels
 +
*** Add to menu
 +
* Timeline
 +
** Keystrokes (Disable Listener?)
 +
** JSON from file, JSON from notebook
 +
* Tabs
 +
** Start with CSS
 +
** Add divs to tabs?
 +
* Reference Support
 +
** Format of MD ref
 +
** Rendered MD - Codemirror overlay?
 +
** Reference Section Style - Footnotes vs. Reference Section
 +
** Database - Bibtech, JSON
 +
 
 +
 
 +
Polishing Done Today:
 +
 
 +
* Section Labeling:
 +
** Made much simpler. Now replaces any combination of digits and dots of any length at the start of sections with appropriate heading for that section.
 +
** All error messages are displayed in one alert to the user.
 +
*** Possibly want to add a "don't show this message again" function.
 +
** Code replaced on the dropbox with the same name
 +
* TOC:
 +
** Now adds the appropriate number of "dummy levels" when sections are skipped by the user.
 +
** New source code is on dropbox under the same name
 +
 
 +
 
 +
For Cole to check out:
 +
 
 +
* http://isbndb.com/api/v2/docs
 +
 
 +
== Tuesday, July 15th, 2014 ==
 +
 
 +
Polishing done today:
 +
* Section Numbering:
 +
** Added button to toolbar!
 +
** Added functionality that removes the section numbers if button is pressed again with no changes to the current numbering
 +
* Table of Contents:
 +
** Added button to toolbar!
 +
** Added functionality that searches the notebook for an already existing table of contents and replaces it with an updated one. Otherwise creates a new on at the top of the notebook.
 +
 
 +
To do tomorrow:
 +
* Replace links in entire document when renumbering sections
 +
* Tabs???
 +
* Disable listener of timeline

Latest revision as of 20:17, 15 July 2014

Goals:

  • be able to use ICalico via a server for fall 2014 courses (Programming Languages, and ESEM)
  • documentation
  • examples
  • JavaScript visualizations
  • JavaScript SpreadSheet interface
  • spelling checker
  • bibliography support
  • commenting by others
  • grading support
  • other functionality as needed
  • clicker-style feedback
  • question/answer widget
  • wiktionary (in-notebook word look-up)

Monday, June 30, 2014

Documentation:

Source:

Spelling Checking:

Miscellaneous:

Tuesday, July 1, 2014

Wednesday, July 2, 2014

JavaScript libraries:

ICalico Notebooks with Visualizations:

Bugs:

  • No vertical bar escape

Thursday, July 3, 2014

Hints on spelling checking:

ICalico documentation:

  • ICalico - the only docs we have so far


Mattie's Wishlist:

  • Being able to make the lines of tables invisible
  • Being able to have reference-style links be defined in any cell in the notebook

Monday, July 7th, 2014

Goals for the week:

Tuesday, July 8th, 2014

Testing and added functionality of automatic section numbering:

  • Discussed several new features with Mattie to make section numbering more user-friendly, including:
    • Added alerts that warn user when missing intermediate headers
    • Added additional alerts warning users when the first header cell in their Notebook is not a Header 1 cell
    • Determining when parts of certain user-defined titles should/should not be replaced
  • Tested more extensively, removing several bugs with replacing already existing headers
    • Users cannot name sections of their notebook titles that match the defined section numbering pattern (i.e. naming a section "1.5 Pies" will delete '1.5' and replace it with the correct section number for that section, even if '1.5' was intended to be part of the title)
  • Successfully generated section numbering for Mattie's Reference Guide


Completed Raw Implementation of Table of Contents Generator:

  • Code is labeled "Table of Contents Code" on Dropbox
  • Mostly working with few bugs
  • Several design questions that can be discussed in the future
  • Put a new copy of the reference guide (Title: "Reference Guide Plus Code") in the Dropbox folder which demonstrates both Section Numbering and Table of Contents Generation!

Known Bugs:

  • Making a markdown link that contains ")?)" forms some sort of escape and will not link properly. Cause unknown. EDIT: Fixed 7/9/2014


Doc Writing Update (from Mattie):

  • Finished explanation of toolbar, with exception to the restart kernel tool and the cell toolbar drop down menu, both of which I am trying to figure out the function of
  • Fix internal links so that they don't open up a new window (with Cole's help)
  • Introduced several new sections to the whole guide, including one that hopefully will link to Cole's automatic section numbering program
  • Currently trying to write a section on how to turn your Notebook into a slideshow, but I'm still figuring out how to do it for myself.

Wednesday, July 9th, 2014

Bug Fixes:

  • Added a fix to remove trailing spaces from links for the table of contents generator
  • Added a fix to replace all parentheses with their encodings (%28 and %29 respectively) fixing the bug causing links with parentheses to render incorrectly.


Potential New Bugs For Discussion:

  • Unordered lists do not render if the indentation level increases by more than one tab at a time. Notebooks with headers that are inconsistent in this way (i.e. jumping from header 1 to header 3) will not render their table of contents correctly. However, this could warn users of potential errors within their notebook.


Timeline Work:

Thursday, July 10th, 2014

Doc Writing Update (From Mattie)

  • After trying to figure out how to view my notebook as a slide show, getting very confused in the process, and asking both Ian and Cole for help, I have determined that there currently is no super easy, intuitive way to do this. Ian set it up so it's not too hard, but it does require entering bash commands in terminal. I'm not sure it makes sense to document this process right now, because hopefully we can change it to be more user/novice user-friendly.
  • Similarly, I am interested in talking about Cole's useful table of contents and section numbering code, but I don't know how it will eventually be implemented for any given user, so I'm holding off on procedural documentation for that function as well.
    • Doug: We'll put those options (Table of Contents and Heading Numbering) on the menu in the notebook.
  • Also, Cole did me a favor and wrote a very simple find and replace code that I think could be turned into a useful tool for humanities and social science students writing papers. In my case, it just replaced every instance of the phrase "IP[y]" and replaced it with "Jupyter".
    • Doug: not sure if we can write a find-and-replace version that will be good enough to be used.
  • I've finished the section on Keyboard short cuts, though right now it just directs the user to the help menu. I wasn't sure reduplicating the a legend for all the keyboard short cuts directly into a cell of the reference guide notebook would be that helpful, but I can do that if it does turn out to prove worthwhile.


Timeline Updates:

  • Have figured out the correct format for JSON data in order to render a timeline using a file instead of googledocs
  • Current embedding code breaks a notebook when run, rendering it useless:
    • All functionality is lost, including keyboard shortcuts, backspacing already written text, etc.
    • <div> tags seem to function fine otherwise so something about the scripts being run seems to be the problem
  • I've tried several different methods of embedding this code, including the two methods listed in the timelineJS documentation, and using python to call the HTML display functions
  • Generating proper JSON format from a markdown table should be fairly easy as the format is basically straightforward

Friday, July 11th, 2014

Mattie and I had quite a long discussion about referencing support today (3+ hours). Summary is below:

Bibliography Support:

  • What style do we use? What style is useful?
    • Footnotes
      • Doesn't really make much sense in a notebook
      • Most useful style
    • Scientific ([1]) Linking
      • Easy to implement
      • Not as useful in humanities
    • MLA
      • Easy to implement
      • Useful, but doesn't really require much support
  • What sort of interface do we want?
    • Markdown cell with reference information
      • Pros:
        • Store all your bib info easily in one document.
        • Automatic citation generation and ordering
      • Cons:
        • Cell will get rendered (Possible fix with html commenting)
        • Formatting might be difficult (Tag cell with %bib or something similar)
    • Separate notebook
      • Pros:
        • Very organized
        • Formatting is easy to define and accessing isn't hard
      • Cons:
        • Not all in same notebook
        • Non-computer scientists might find this format/organization more difficult
  • Extra Ideas:
    • Tagging feature for organizing thoughts during pre-writing/planning
    • Tags are just HTML comments. Could include page number and will stay once everything is rendered, but not appear in rendered cell.
    • Mouse-over titles are full citation

Monday, July 14th, 2014

Goals for the next three weeks:

  • Polishing:
    • Section Labeling
      • Simplicity
      • 1 Warning at end
      • Ask about header cells. Dealing with headers in markdown
      • Add to menu
    • TOC
      • Dummy Levels
      • Add to menu
  • Timeline
    • Keystrokes (Disable Listener?)
    • JSON from file, JSON from notebook
  • Tabs
    • Start with CSS
    • Add divs to tabs?
  • Reference Support
    • Format of MD ref
    • Rendered MD - Codemirror overlay?
    • Reference Section Style - Footnotes vs. Reference Section
    • Database - Bibtech, JSON


Polishing Done Today:

  • Section Labeling:
    • Made much simpler. Now replaces any combination of digits and dots of any length at the start of sections with appropriate heading for that section.
    • All error messages are displayed in one alert to the user.
      • Possibly want to add a "don't show this message again" function.
    • Code replaced on the dropbox with the same name
  • TOC:
    • Now adds the appropriate number of "dummy levels" when sections are skipped by the user.
    • New source code is on dropbox under the same name


For Cole to check out:

Tuesday, July 15th, 2014

Polishing done today:

  • Section Numbering:
    • Added button to toolbar!
    • Added functionality that removes the section numbers if button is pressed again with no changes to the current numbering
  • Table of Contents:
    • Added button to toolbar!
    • Added functionality that searches the notebook for an already existing table of contents and replaces it with an updated one. Otherwise creates a new on at the top of the notebook.

To do tomorrow:

  • Replace links in entire document when renumbering sections
  • Tabs???
  • Disable listener of timeline