To manage your bibliography and in-text citations, which tools are best to use in Emacs? I am pretty confused about for instance helm-bibtex, org-ref, and ebib. Are these different packages for the samae thing? Thanks!
org-ref: a reference management system that integrates tightly with org-mode. I think of it like a lightweight Zotero but fully inside emacs (eg you can edit bibtex files, insert citations, search/download PDFs for references, insert bibliographies, etc). The youtube video on the Github page does a pretty good job explaining what it does and its intended workflow.
helm-bibtex: a search tool for .bib files. Execute helm-bibtex and it presents a list of whatever .bib files you configure it to search. When you 'select' something you have the option of navigating to the URL, opening the PDF, inserting the entry as a citation, inserting the BibTeX entry, etc. Also there is another command called ivy-bibtex which is confusingly part of the helm-bibtex package which does the same thing but with ivy. Furthermore, org-ref depends on helm-bibtex so consider the features of the latter to be a subset of the former.
ebib: as far as I can tell this is separate from the other two but looks like it overlaps with org-ref (or at least it has the ability to download PDFs, insert citations, follow URLs, search .bib files, etc). The main difference is that it appears the intention for ebib is to provide a nice tool for editing .bib files themselves, although it can do more than just that.
FWIW I personally use Zotero for managing my .bib files and then search/insert from them with ivy-bibtex/helm-bibtex when writing. I have ebib and org-ref half-configured but I never really needed to use them given that Zotero makes up for alot of the features that don't directly involve writing a manuscript. I also prefer to write in straight LaTeX rather than use org-mode's export functionality (just personal preferences), so this also removes the incentive for me to use org-ref since it seems geared toward writing in org-mode itself.
You can obviously do whatever you want just using Emacs packages and not rely on Zotero at all, but that should give a sense of what functionality each package provides.
Related
I am working on a Firefox extension it is a context menu for automating bbCode, HTML, MarkDown, etc.
It is functional now, but I have a file which is the size of the rest of the code combined, an Excel spreadsheet. (Yes, I know, lame)
I use it as a database for organizing the menu IDs, arguments, internationalization, etc.
It's useful, for me at least, and I want to make it available, but it is not properly a part of the application, it should be a part of the background documentation.
Is there a way in Github/Git to separate documentary files from those that a part of execution of the code?
I've looked through Github, and I haven't found a spot (with revision control) to put this.
I need to implement a documentation generation solution for my workplace and have narrowed it down to the three mentioned in the title. I have been able to find very little information in the way of formalized comparisons between these solutions, and I'm hoping that those of you with experience in one or more of the above can weigh in:
Here is what I have been able to glean from my initial pass:
HeaderDoc Pros: Consistent with apple's existing docs, compatibility with making apple docsets
HeaderDoc Cons: Difficult to modify behavior, project is not actively worked on, many have switched away from it (meaning there must be something deficient, though I can't quantify it).
Doxygen Pros:
Active support community b/c of wide use base, very customizable, most output types (like latex etc)
Doxygen Cons:
Takes work to make it look/behave consistent with apples docs, compatibility with apple docsets is not as simple
AppleDoc Pros:
Looks consistent with apple's existing docs, compatibility with making apple docsets,
AppleDoc Cons:
Issue with documentation of typedefs, enums, and functions, actively being developed
Does this sound accurate? Our desired solution will have:
Consistent look and feel with apples objective-c class reference
Ability for option-click to pull up documentation reference from within Xcode, and then link to the doc (just like apple's classes)
Smart handling of categories, extensions, and the like (even custom categories of apple's classes)
Ability to create our own reference pages (like this page: Loading… that can include images, and be linkable from generated class references seamlessly, like how apple's UIViewController class reference links to the linked page.
Easy to run command line commands that can be integrated into build scripts
Graceful handling of very large codebase
Based on all of the information above, are any of the above solutions clearly better than the others? Any suggestions or information to add would be extremely appreciated.
As the creator and lead developer of doxygen, let me also provide my perspective
(obviously biased as well ;-)
If you are looking for a 100% faithful replica of Apple's own documentation style, then AppleDoc is a better choice in that respect. With doxygen you'll have a hard time to get that exact same look, so I would not recommend to try.
With respect to Xcode docsets; Apple provides instructions how to set that up with doxygen (written in the time Xcode 3 was released). For Xcode 4 there is also a nice guide how to integrate doxygen.
As of version 1.8.0, doxygen supports Markdown markup, as well a large number of additional markup commands.
With doxygen you can include documentation on the main page (#mainpage) as well as on subpages (using #subpage or #page). Inside a page you can create sections and subsections. In fact, doxygen's user manual was completely written using doxygen. Besides that, you can group classes or functions together (using #defgroup and #ingroup) and inside a class make custom sections (using #name).
Doxygen uses a configuration file as input. You can generate a template with default values using doxygen -g or use a graphical editor to create and edit one. You can also pipe options through doxygen via a script using doxygen - (see question 17 of the FAQ for an example)
Doxygen is not limited to Objective-C, it supports a large range of languages including C, C++, and Java. Doxygen is also not limited to the Mac platform, e.g. it runs on Windows and Linux too. Doxygen's output also supports more than just HTML; you can generate PDF output (via LaTeX) or RTF and man pages.
Doxygen also goes beyond pure documentation; doxygen can create various graphs and diagrams from the source code (see the dot related options). Doxygen can also create a browsable and syntax highlighted version of your code, and cross-reference that with the documentation (see the source browser related options).
Doxygen is very fast for small to medium sized projects (the diagram generation can be slow though, but nowadays runs on multiple CPU cores in parallel and graphs from one run are reused in the next run).
For very large projects (e.g. millions of lines of code) doxygen allows the projects to be split into multiple parts and can then link the parts together as I explained here.
A nice real-life example of using doxygen for Objective-C can be found here.
The development of doxygen highly depends on user feedback. We have an active mailing list for questions and discussions and a bug tracker for both bugs and feature requests.
Most users of doxygen use it for C and C++ code, so naturally these languages have the most mature support and the output is more tuned towards the features and needs for these languages. That said, also wishes for and issues with other languages are taken seriously.
Note that I do nearly all doxygen development and most testing on a Mac myself.
I'm the author of appledoc, so this answer may be biased :) I tried all mentioned generators though (and more) but got frustrated as none produced results I wanted to have (similar goals as you).
According your points (I only mention appledoc and doxygen, I don't recollect headerdoc that well):
Consistent look: appledoc out of the box, other need to tweak css, but probably doable.
Generation of documentation sets (for Xcode references): appledoc full support for searchable and option-clickable documentation out of the box, doxygen generates xml and makefile which you need to invoke yourself. Additionally appledoc supports published docsets out of the box.
Categories: appledoc allows you to merge categories to known classes or leave them separate, foundation & other apple class categories are listed separately in index file. doxygen: this wasn't working best when I tried it.
Custom reference pages: appledoc supports out of the box using either markdown or custom html, doxygen: you can include custom documentation to main page, don't know if you can include more pages.
Easy command line: depends how you look at it: appledoc can take all arguments through command line switches (but also supports optional global and project settings plist files) so it should be very easy to integrate with build scripts. doxygen requires usage of configuration file to setup all parameters.
Large codebases: all tools should support this, although didn't compare timewise. Also not sure if any tool supports cached values (running over previously collected data in order to save some time) - I am looking into adding this for next major release.
It's some time since I tried using other tools, so above mentioned issues with doxygen/headerdoc may have been addressed! appledoc itself also has disadvantages: like you mention there's no support for enums, structs, functions etc (there was some work done in this direction, check this fork), and it has it's own set of issues that may prevent you using it, depending your requirements.
I am currently working on major update that will cover most glaring issues, including support for enums, structs etc. I'm regularly pushing new stuff to experimental branch as soon as I finish larger chunks and make it stable enough, so you can follow the progress. But it's still very early and progress depends on my time so it may take quite a while until working solution.
Xcode 5 will now parse your comments to search for documentation and display it:
You don't have to use appledoc or doxygen anymore (at least when you don't want to export your docs). More information can be found here
hey everyone, we just added a nightly action to process the entire source tree with doxygen and place the output onto development webserver.
We also already have a sharepoint structure which holds design documents for various modules/projects. Currently, the level at which we are keeping this documentation is relatively high. We discuss structures of modules and talk about the major classes, but never go down to the individual method level. I wanted to bridge that gap by having hyperlinks in the SDS word documents that would point to doxygen output.
I noticed the links look like this:
http://example.com/docs/ProjectName/d4/d98/class_c_reader.html
http://example.com/docs/ProjectName/d4/d16/class_c_stream.html
The part that sketches me out a bit is "d4", "d98" and "d16" strings in the path. If I copy these links and create the hyperlinks, does anyone know if these URLs are guaranteed be preserved in the future. As I said, entire doxygen output gets regenerated nightly.
You can disable the d4/d98 subdirectories by disabling CREATE_SUBDIRS in the doxygen configuration.
Whether the name of the HTML files will stay the same I do not know for sure but from what I have seen when using doxygen it seems so. If you want to know for sure you can always look at the doxygen source.
Probably these links will not stay permanent.
Furthermore, Doxygen has a XML representation of the generated documentation but even this interface resp. the corresponding DSD has been changed with new releases of doxygen. This is quite frustrating, as we had used the XML representation for a similar application with the assumption that the structures would be kept identical with every new release.
I have a workflow where I use grep and other tools in a shell for searching in different projects even though my main editor is emacs. I usually work on bug fixing and minor development of source code that is often unknown to me so searching the code is important. The langages I mostly work in are php, ruby, java, perl and sometimes python.
Is there some common IDE extension in emacs that would enable me to have functionality like "goto definition" from multiple files that span all these languages? Are there some other modules that could be useful, either code browsing or indexed search?
If you want to work with lots of different languages, ctags is pretty flexible. See the EmacsWiki for instructions on integration of ctags.
Code browsing can mean a bunch of different things. The mode you mention of using grep implies to me you are looking for function definitions, or perhaps looking for uses of a particular function.
While CEDET supports all the languages you list (some with the ctags parser), starting fresh in a new source code area is something CEDEt isn't too good at until it has indexed the entire project for those tasks you listed. You can, however, use GNU Global or idutils. I think idutils supports more languages.
In CEDET, the `semantic-symref' and related commands will do a grep-like operation with grep, or global, or idutils (depending on what type of tag table you created.) Unlike grep style output, the symref output buffer shows which functions are using the command in question. You can then execute macros on the hits of the symbol you care about to do large refactoring operations.
CEDET also supports a tags like jump to function, though if you are already using something like ctags that works fine too. CEDET is better when it comes to handling polymorphism in some cases.
With CEDET, you can also get structured browsing via imenu, speedbar, and ECB (the emacs code browser). ECB is particularly good in that the methods buffer allows you to quickly navigate to different parts of a class. Particularly handy for classes where the pieces are spread around, like in C++. CEDET can even create cute UML diagrams of class inheritance structures which are connected to your code.
CEDET does take some learning, and some of the languages you list are not fully supported for all the tools, though the basic browsing discussed above should be ok.
etags-select (which you can get from ELPA) makes browsing your TAGS file nicer, in my experience, if you bind M-. to etags-select-find-tag.
As well as etags/ctags try running grep with M-x grep rather than in a shell, to get clickable links in Emacs rather than having to manually find the file and line matching the grep output.
For code browsing, you can also use M-x imenu-tree
Tags browsing, with dynamic completion, filtering (substring, regexp, fuzzy), cycling:
http://www.emacswiki.org/emacs/Icicles_-_Emacs_Tags_Enhancements
What's the best solution for authoring HTML5 in Emacs? Is there a mode that will do conformance checking?
My best suggestion is to use nxml-mode (available as packages in several linux distributions if you're on that platform) and load the html5 RelaxNG compact format specifications from HTML5 specification page (or any other source if you have one).
Nxml-mode validates xml files on the fly according to relaxNG specifications and give you nice customization features and handy functions for writing documents faster like inserting end-tags and such. Written by James Clark, so you know the author knows his XML.
If you load it like a system package you can probably just add it to your auto-mode-alist and be good to go. I have just set the following two variables for auto-completion and more docs is available at the first link.
(nxml-bind-meta-tab-to-complete-flag t)
(nxml-slash-auto-complete-flag t)
When it is loaded, just load the file you want and specify the location of the schema for html5, save its location through the menu and you should be on your way. There are also more links to documentation on nxml-mode in the link I provided.
I've just seen this project, which apparently takes care of the necessary work to teach nxml-mode about HTML5:
http://github.com/hober/html5-el/tree/master
An easier to install solution may be web-mode. It definitely plays well with HTML5 and doesn't require you to jump through the XHTML hoops.
JavaScript and CSS blocks work as you would hope.
It also includes the ability to handle common templating languages like php, erb, handlebars, etc.
Check out http://web-mode.org for more details. It's available as a package, at least on MELPA.
I had nXML previously but found the schemas quite cumbersome to install, meaning I didn't get it to work with HTML5. I now use web-mode. Drawback is that there is no real-time validation. But that's cool as there are online-tools for that.
I recommend emmet mode. https://emmet.io/download/
This mode can be enabled in other editors rather than Emacs.