Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
I am currently writing a formal research report, and I'll be including code with this report.
Question: Is there an accepted way of displaying code in research reports? I'm thinking both in terms of font, spacing, et cetera, and whether the code should be displayed inside the document, or in an appendix.
The code will be JavaScript and PHP. None of the sections of code will be more than 25 lines (so they're mere snippets). There will be approximately half a dozen snippets. Each of the snippets will have a couple of paragraphs explaining what is happening in the code, and a discussion on its pros/cons.
I have no contact with the body to whom the report will be submitted to, and they have no published guidelines on how to format code (please do not question these points).
Well it depends on which style guide your paper is being written to comply to...
Usually code should be written in a monotype font so that it is easily readable (E.g. Lucida Sans Console or Courier New). This means that all letters take up the same space on the page.
When I have written bits for publishing I have indented the code 2.5cm from the side and given it a light grey background, in a Lucida Sans Console font... Following C style code indenting.
I would ask your institution if they have a style guide, but as you have a lack of this ability go with a popular style guide such as the Harvard system and make sure you follow the same format throughout.
Here is a list of journals from Google Scholar which display style:
http://scholar.google.com.au/scholar?hl=en&q=PHP+SQL+programming+journal&btnG=Search&as_sdt=2000&as_ylo=&as_vis=0
This is my preference:
When writing inline, get rid of code that is irrelevant to the explanation (such as import
statements as previously mentioned, but potentially also variable declarations that are "obvious" and the like). The goal of code placed inline should be for easy crossreference with the paragraph describing that code block.
Code placed in appendices should be complete (as in - you can put this into your compiler and press go).
Don't be scared of placing heavily cut down code in snippets, along with a reference to the appendix containing the full code - the appendix code is for someone to read/run separately. the inline code is for people to glance at and help understand the specific point of that section.
I would say Courier font with standard text spacing and standard line spacing, all black text, proper indentation.
In terms of the code itself, omit import statements, comments are okay. You may want to add foot notes like {1}, {2}, inline in the code as a comment and reference below in the text that explains the code.
This paper has an example on page 6:
http://www.eecs.berkeley.edu/Pubs/TechRpts/2006/EECS-2006-1.pdf
I realise that this is an old question, but do not forget to number the lines in your code! For one-liners, it's okay to skip numbers, but anything larger, they're almost required.
If you are writing a research report, you should be using LaTeX.
I typically use the LaTeX vancyvrb package and the Verbatim.
However, another option is to use the listings package. It can input a file directly using the lstinputlisting command. It automatically numbers your lines and uses the _ character instead of the space character, but this is programmable. It's really quite nice.
What JD and Ben said.
You should use appropriate, established syntax highlighting. Latex's listings package, mentioned by vy32, has syntax highlighting styles for both Javascript and PHP, as does the Pygments program, which outputs to, among others, Latex, HTML, and RTF.
Related
Within a Markdown editor I want to support text highlight, not in the sense of code highlighting, but the type of highlighting people do on books.
In code oriented sites people can use backquotes for a grey background, normally inline code within a paragraph. However on books there is the marker pen for normal text within a paragraph. That is the classical black text on yellow background.
Is there any syntax within Markdown (or its variants) to specify that the user want that type of highlight? I want to preserve the backquotes syntax for code related marking, but also want a way to enable highlighted user text
My first thought is just using double backquotes, since triple backquotes are reserved for code blocks. I am just wondering if other implementations have already decided a syntax for it... I would also appreciate if someone could justify if this is a very bad idea.
As the markdown documentation states, it is fine to use HTML if you need a feature that is not part of Markdown.
HTML5 supports
<mark>Marked text</mark>
Else you can use span as suggested by Rad Lexus
<span style="background-color: #FFFF00">Marked text</span>
I'm late to the party but it seems like a couple of markdown platforms (Quilt & iA Writer) are using a double equal to show highlighting.
==highlight==
Typora is also using double equal for highlighting. It would be nice it that becomes a CommonMark standard, as mentioned by DirtyF. It would be nice for those who use it frequently, since it is only 4 repeated chars: ==highlight==
If you want the option to use multiple editors, it may be best to stick with <mark>highlight</mark> for now, as answered by Matthias.
Here is the latest spec from CommonMark, "which attempts to specify Markdown syntax unambiguously". Currently "highlighting" is not included.
Editors using ==highlight== from comments mentioned previously:
Typora
Obsidian
Quilt
IA Writer
Feel free to add to this list.
You can use the Grave accent (backtick) ` to highlight text in markdown
Highlighted text
Also works with VS Code extension markdownlint
Grey-colored Higlighting Solution
A possible solution is to use the <code> element:
This solution works really well on git/github, because git/github doesn't allow css styling.
OBS!:
Using the code-element for highlighting is not semantic.
However, it is a possible solution for adding grey-colored highlighting to text in markdown.
Markdown/HTML
<code> <i>This text will be italic</i> <b>this text will be bold</b> </code>
Output
This text will be italic this text will be bold
Roam markdown uses double-caret: ^^highlight^^. Andrew Shell's answer mentions double-equals.
The accepted and clearly correct answer is <mark> from Matthias above, but I thought I had seen carets in some other flavor of markdown. Maybe not. I want to transform my ^^highlights^^ to <mark>highlights</mark> in pandoc conversion to html, and somehow ended up here...
Probably best bet is just use html e.g
<pre><b>Hello</b> is higlighted</pre>
Hello is higlighted
Remember nearly all html is valid in markdown too.
I need to maintain some slides in both latex beamer and in powerpoint. (This is to make slides available for instructors elsewhere, too, 90% of which do not know how to use latex and are unwilling to learn it. and I am a latex guy on linux.)
I have tried the route via Libreoffice (and opendocument), but this did not come out well. right now, the best method that I have found is to author pdf in beamer, then run it through a nuance OCR program to get MS Word...and not even go all the way to Powerpoint (which is where I really need to be).
If I only had a markup language that produced nice Powerpoint, I could probably code a perl translator from markdown to this intermediate markup language. (going from markdown to latex beamer is relatively easy.)
I don't think this exists, but hope springs eternal. after all, it is almost 2014 now. does anyone know of a solution?
One solution is to use odpdown: It converts markdown to the OpenOffice Presenter format, which can be imported into PowerPoint.
It is not yet complete, i.e. table support is missing and possibly not running on certain Windows setups, but nevertheless it could be a start. Possibly, you have Linux running, where it seems to work.
Steve Rindsberg's answer in the comments works on PP 2007 works! Let me repeat it here:
I suspect that PowerPoint is the likeliest solution. ;-) But what sort
of slides are you creating? If they're simple heading and bullet point
slides, all you need to produce is a simple text file. Any text that
starts in the left column will be the heading of a new slide. Indent
one tab and it becomes a first-level bullet point under the current
heading; indent two tabs, it becomes a second level bullet point and
so on. Simply use File | Open on the text file to pull it into PPT.
Steve: Is this all that PP converts? Or is there a reference of other "sneaky" markup that PP knows about?
(pandoc: unfortunately, the conversion from libreoffice to powerpoint is pretty poor when I tried it last. I also tried to save and understand the powerpoint xml format, but that was REAL bad.)
The easiest way to handle this is to work with:
RStudio (and R if not already installed)
RMarkdown
Pandoc 2.0.5 (minimum)
Install those 3 (or 4) items, then read: https://bookdown.org/yihui/rmarkdown/powerpoint-presentation.html
The installation time is worth the time saved copy-pasting everything from scratch.
I also am a Linux guy and I also use LateX engines to create nice documents. Based on my experience, here's what you should do :
Stop writing directly in LaTeX and start using org-mode to write documents instead (I spent years writing in LaTeX and now it's over (except when I use modernv package))
Org supports latex math formulas and .org files are easily exported in .tex files
Org can also be easily exported in markdown
Once you have your markdown, there are several tools that will allow you to create a PowerPoint. Two of them are pandoc and md2pptx
I use Mma mainly to solve relatively small problems.
I want to start using it also to prepare my presentations and documents, but I am having troubles to learn how to do it from the embedded help, and I guess some good resources may be available elsewhere.
Do you know any useful pointers (books, papers, videos ...)?
Do you have a "bag of tricks" to post here?
Edit
This question received two answers so far (#mzabsky's and Mr.Wizard's) and although both are useful, perhaps my concerns are much more basic. So I am posting an example of the kind of things I am unable to do (or understand how to discern how others did them).
I took the following example from The Mathematica Journal (the notebook at the left on the following image - click on the image to see full size):
So, some issues, just to get the idea of my troubles:
1) I copied the text to my .nb on the right, formatted it with the same style (text), but the appearance is different, so I guess the style definition is different. How can I copy the style definitions from one .nb to the other?
2) The table below the text block doesn't have an attached style. How was it formatted? Where is the background color defined?
I would like pointers to read (or videos to look, or whatever) about these issues. I don't want you to write down here a book on Mathematica formatting!
Summary of the links posted in answers
A Mathgroup thread (John Browne) and here (David Park and
Selwyn Hollis)
Advice from Bob Ueland
The Writing Assistant Palette
David Park's notes
Simon's documents
Tips for Mathematica SlideShow presenters
Notebook formatting
Presentations with Mathematica
Videos
Tips for Mathematica Slide Show Presenters
How to - Automatic Slide Show
Create a Lecture Notebook
I use Mathematica to take lecture notes in real time without any major issues (while the proud TeX guys struggle hard to keep up :) ). I have also used it for most math-related homework/assignments I wrote during past two and half years on university.
Before you start, you may want to look at some of these video tutorials.
Also, a few recommendations from me:
Keyboard shortcuts are the key to type fast. Ctrl+9 for inline math cell, Ctrl+6 for superscript, etc.
Learn symbol identifiers for the "esc - symbol - esc" notation. "sum" for Sum, "es" for empty set...you can find list of these in the Mathematica documentation. I have encountered only very few symbols I wanted to type that don't have the esc notation name (for example, leftwards double arrow or double right tee).
Type all math-related stuff into inline math cells. The math cell will do some of the math related formatting for you - put spaces where they belong, render all variables and symbols in italics, etc.
Use the preformatted templates found in "New"->"Styled Notebook".
Do not use ENTER for breaklines, individual paragraph should go into separate text cells (Ctrl+Shift+D) so Mathematica can break the content into individual pages/slides correctly.
In-built Mathematica PDF export sucks big-time; I use CutePDF printer for this.
Also, save often and back up often (Dropbox/Syncplicity are the ideal solution), one misplaced keyboard shortcut can turn hundred hours of work worth document into a goulash (trust me, been there) :)
Example of lecture notes I took in real-time during lecture (it is in Czech, but that doesn't matter much).
I agree with all that mzabsky said in his answer.
Here's a few of extra things:
I find it useful to make statements using a Text or DisplayFormula cell then manually group a Mathematica check/proof to the statement which is then collapsed and can be displayed when you want.
The Writing Assistant Palette has quite a few useful constructions in it that you can learn from.
Finally, I found it really useful to make my own style sheet for a couple reasons:
1) the built-in ones are a bit ugly; 2) it really helps you to understand how the notebooks work.
To see examples of the stylesheet I made (which I don't claim to be perfect - I didn't bother making it work in all screen environments) look at some of the files in ftp://ftp.physics.uwa.edu.au/pub/MATH2200/2010/. I use a similar stylesheet in all of my notes - I have many research projects primarily contained in Mma notebooks, eg http://arxiv.org/abs/1102.3043.
Like Mr Wizard, I also recommend David Park's notes as a starting point. Also, you should study stylesheets that you like by going to the Format menu and clicking "Edit Stylesheet". Don't forget to follow the links through the cascade of stylesheets (version 6 onwards).
To answer the questions in your edit: Once you are viewing a notebook's stylesheet, you can save it, edit it, and use it in your own documents. Stylesheets in
$UserBaseDirectory/SystemFiles/FrontEnd/StyleSheets are automatically available in the menu. You can then use that stylesheet in any notebook by simply selecting it from the menu.
The formating in the screenshot that you posted is all contained in the stylesheet. This includes the grey background in the table.
Addendum:
When distributing notebooks to others, if the stylesheet is external from the notebook, then other people will not see it as you do. To include the stylesheet into the current notebook, you need code like
ss = StyleDefinitions /. Options[EvaluationNotebook[]]
fn = ToFileName[{$UserBaseDirectory, "SystemFiles", "FrontEnd", "StyleSheets"}, ss]
If[FileExistsQ[fn],
style=Get[fn];SetOptions[EvaluationNotebook[],StyleDefinitions->style];,
Print["Can not find file"]]
(Assuming the file is in stored in the conventional place)
Here's an EmbedStylesheet.m that is an improved version of the above.
A Mathgroup thread on embedded stylesheets, particularly here (John Browne) and here (David Park and Selwyn Hollis) might be of interest.
I find stylesheets problematical. In particular I don't like having to remember to embed a stylesheet before I give the notebook to someone else, or before I try to print from an unfamiliar computer. However, along with David Park's tutorial (referenced above by Mr Wizard), I find this advice from Bob Ueland very useful.
If you browse the back-issues of The Mathematica Journal you will see that articles are available in Notebook format. These may be a useful reference.
Edit
I cannot recall a good formatting tutorial at the moment. You can use Show Expression (Win: Shift+Ctrl+E) to view the code expression for a block, such as the table in your example. While one may not enter code by hand in the same form, it can give indications of the options or methods that are used. Code can also be procedurally produced as needed.
I will add links as I find or recall them.
David Park's StyleSheet creation notes
Tips for Mathematica SlideShow presenters
These are brief, but may still be useful:
Notebook formatting
Presentations with Mathematica
A few years ago I read an article about a neat way to analyze a large code-base.
The idea was to zoom out so far that patterns of indentation and block length are all that is really visible.
The author wrote about printing out code with very small fonts and looking at the results from 10 feet back. I believe the author also had some tools for reformatting code and producing images for this technique, in such a way that paper could be avoided.
I can't find the right search query to bring this up. Anyone have any ideas?
The text editor Sublime Text has a zoomed-out overview of your code on the left of the window, and can be used to scroll.
I've done this myself, that is print to paper with very small fonts and step back. If you want to avoid the paper route then perhaps you can print to PDF?
Or use and editor that can zoom in and out by changing font size. I use SciTE and Komodo Edit, both based on the Scintilla code editing engine and both allow me to hold down the ctrl key and use the mousewheel to change font size (just like web browsers).
With a bit of Google-fu I found references that this (ctrl+mousewheel) may also be implemented in Visual Studio and XCode. Can anyone confirm?
I think you are referring to Software Visualization? If you search for Code Visualizer, you maybe able to find a few products out there that does it but there are more focusing on aggregating the measurements information/metrics together for software comprehension and not necessary as a way to view or navigating to code only.
Some of the tools include Code city, code crawler or code visualizer. Michele Lanza and his team did some great work in this area in the recent years, however some only has support for certain language/platform so be mindful if they are going to be useful for you.
http://www.inf.usi.ch/faculty/lanza/
http://www.inf.usi.ch/phd/wettel/codecity.html
Could extract all the types, classes, etcetera, and put them into a tool such as graphviz and generate a graph.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I need some tool to display text containing ANSI codes correctly on Windows. No full support needed, but at least coloring/bold is a must.
Reason: My logger/debug module produce nicely rendered rich output with important sections colored using ANSI codes. This helps a lot when debugging on the serial terminal, but if I dump the debug to a file or copy-paste it into a text editor on Windows (interactive remote debug is not always viable), at best all the ANSI codes are stripped, at worst they are rendered as junk characters obscuring the real data. Rudimentary editing capabilities would be appreciated to be able to pick out specific parts, annotate, and so on.
The open-source editor Atom has the package language-ansi-styles. It supports all kinds of formatting except ;r;g;b.
You might have some more luck with ASCII/ANSI utilities, like the ones listed here:
List of ASCII/ANSI/NFO utilities
**Note: some files on this page might be outdated, you might find newer versions of these utilities on their respective homepages.*
For example, the latest version of NFOPad can be found here.
I've been looking for a solution to display the ANSI colors as well (for program debug output readability) and stumbled upon Sublime Text (paid software with trial http://www.sublimetext.com/) with a the ANSIescape package (https://github.com/aziz/SublimeANSI or installed through the package control).
It supports coloring and the bold escape is recognized but not displayed, although a special color can be assigned to it in the settings file. Also worth noting that this plugin shows text in read-only mode, and needs to be turned off if editing is necessary.
Here is the screenshot provided on the github, and I have personally tried it and verified it works:
If you're primarily interested in viewing the file instead of editing it, Ansifilter will convert it to HTML, which you can then view and at least search in your browser, or RTF if wordpad would be good enough (hard to imagine). Huh, looks like there's a notepad++ plugin version on the download page, too, so that might be perfect if it allows you to load into notepad++.
http://www.andre-simon.de/doku/ansifilter/ansifilter.html
There's also a different plugin for vim which colors text according to ANSI codes.
http://www.vim.org/scripts/script.php?script_id=302
However, while it highlights the text in the correct color, it leaves the ANSI codes themselves in there (in a faded, near-background color) which probably will mess up any alignment formatting in the file, as well as making it harder to move around the file (lots of "empty space" to wade the cursor through, searching for a word won't match if there's an ansi code in the middle of it, etc.). There's a patch it can take advantage of to hide the codes too, but that would require patching and then recompiling vim itself from source.
Yeah, suggesting vim is pretty unhelpful if you aren't a vim user already, it has too huge of a learning curve, I know. But it might be useful to the vim users out there.
I know it won't be of much help - but I was looking for the exact same thing on linux; was just trying to view some log outputs that had bash ANSI color codes inside. Unfortunately, those ANSI color codes were spread across several lines - meaning 'cat'-ing the file and piping into 'less -R', 'most' and similar tools, would simply display the starting line where the color originated, but not the subsequent lines that should've been colored.
Funnily enough, I thought usual Linux tools like 'nano', 'gedit', 'vim' and whatnot would have capabilities for ANSI color codes in a text file, but it's very modest out there with info on ANSI color in text files in these editors. I've only found info on ANSI color for the test editor 'joe':
Cheap ANSI Color! - http://tldp.org/LDP/LG/issue01to08/articles.html#ansi
but couldn't get the recommendations there to work (also couldn't get 'emacs' to work either, at least not by directly reading a text file with ANSI color characters inside).
The good thing - it seems what you need, if you need ANSI color in text, is to look for ASCII art / NFO utilities as recommended above - and the one that I finally found, and was working for me, was tetradraw (via www.linux.org/apps/AppId_42.html ; can be sudo apt-get installed in Ubuntu ... actually, tetradraw is the name of the drawing/editor part - however there is a separate viewer that also works with ANSI color codes, tetraview).
Well, who would have thought, that you need to track down an ASCII art utility, in order to read log files :)
Anyways, hope this may somehow help in the further search of ANSI color text editors for Windows, too.. Cheers!
If you just want to view then the terminal program "Tera Term" can do this. Just click "File" -> "Replay Log" and select your file containing the ANSI codes.
You can download Tera Term here:
http://logmett.com/index.php?/download/tera-term-477-freeware.html
In Emacs, just eval the following before opening your .nfo file:
(add-to-list 'auto-coding-alist '("\\.nfo\\'" . cp437-dos))
I have been a while testing multiple programs on the URL refered by Andras Vass with no results (they don't show colors, or they keep showing ANSI codes as a mess of characters).
Tired of searching I have finally found ANSIFilter (not the NotePad++ plugin refered by Jeffson), the only that works for me.
I have added it to Windows context menu, so I can now easily open my ANSI text files.
I would be surprised if emacs can't do that.
At least with the embeded shell.
There are:
http://www.emacswiki.org/emacs/AnsiTerm
http://www.emacswiki.org/emacs/MultiTerm
http://www.emacswiki.org/emacs/ansi-color.el
Update: as it had been pointed, they are just term output colorizers. But if you can edit the shell buffer contents in emacs too, eg. cat file && colorize.
But wait a minute, I had just found these:
http://vaperized.com/ansiexpress.htm
http://www.syaross.org/thedraw/
http://picoe.ca/products/pablodraw/
If the debug logging of your application goes via 1 class/function, you could try to split the output so that:
ANSI-like logging is shown on the terminal/console
HTML-like logging is written to file
For your application all logging goes to this class, and this class splits the output to terminal/console and file.
Make a 'standard' in your logging class for specifying colors and boldness (e.g. predefined codes like Ctrl-A means red, Ctrl-B means bold, ..., or specific methods in the logging class for setting the color and boldness, or maybe even the ANSI-codes), and translate this in your central logging class to:
the correct ANSI codes on terminal
the correct HTML codes in file
Alternatively, I think that instead of HTML you also could use rich-text, but I don't know all the possibilities of rich text so you may have to look this up.
You could try notepad++ (see http://notepad-plus.sourceforge.net/uk/site.htm). It's pretty powerful (Scintilla based) and has an option to view non-printable characters (like line-breaks and the like).