As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 11 years ago.
Only a few people recommended to use Sphinx at the beginning of the year.
Sphinx has developed rather fast recently. I noted today that Sage has made a change from direct editing with LaTex to Sphinx. This is evident in William Stein's answer on 2nd April about Sage's tutorial
The tutorial is not a latex document anymore. It's an entirely
different Sphinx document that can output pdf.
It suggests me that Sphinx may be at a level such that it is suitable for me.
Is Sphinx better than LaTex in writing manuals/books?
We wrote a book with sphinx but we had to tweak the tex file produced with a Python script.
Take a look at this thread, in the book building tool section
Here a some changes we made to the original LaTeX file:
documentclass = 'book'
added frontmatter, mainmatter and backmatter
added a new style to fncychap.sty
two columns index instead of one columns
some changes in the page header
everything is black & white
links
titles
images (using imagemagick to convert the images in greyscale)
tips and notes displayed in a nicer box with icon
better float placement on pages to optimize the space used
We also made minor changes to book.cls and sphinx.sty
With all these tweaks, we are very happy with the result.
Well, there is at least one book printed using sphinx and rst2pdf
Some sample documents generated via sphinx and rst2pdf here:
http://freedrive.com/folder/236385
And here:
http://freedrive.com/folder/236380
Specially check the python library reference and the django book.
This is output from the development branch and has bugs (for example, the TOC is often on the wrong side of the page) which are being fixed.
I prefer Sphinx to Latex for writing manuals for two reasons:
You can build nice HTML, PDF, htmlhelp and qthelp versions of the manual with minimal effort.
reST syntax is faster to write and I find easier to remember (it's more simple)
A book, however, might be a different story. If I wanted to write a book that has only a printed and a pdf version and contains equations and citations I would go with Latex, because I think it is much more mature than reST and I find it easy to customize.
Btw. I have much more experience in using Latex.
It's better for creating reference documentation, not for writing books.
Is Word a better document production tool?
LaTeX (and TeX) have been around for longer than most of us realise that there were programmes to do that sort of thing and that we were interested in them. LaTeX is almost certainly better than Sphinx (or Word).
Is it better for you? Maybe.
Is it better for me? Unlikely.
Is it better for the average person? Define 'average' then go to point 1.
Related
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I know text editor and IDE questions have pretty much been beat to death, but most of the answers I've found to this question are Windows and Mac specific, and also aren't always free. I've just started rails development and I'm looking for a light-weight text-editor that supports syntax highlighting. I know there is RubyMine, RadRails, and Netbeans. I'll probably always use one of them for big projects, however, sometimes I prefer to stay away from the IDEs (and all the project .xml .config workspace files they create, and the overhead of opening a file that isn't located in a specific "project") and just use a simple text editor. I had been using Scribes in the past for this but it doesn't have highlighting for .rhtml. I've heard people struggle with gedit as well, and I'm nowhere near desperate enough to be running Notepad++ under wine. Sublime seems to be popular but isn't free. Am I being too needy? Is there anything out there that meets the following criteria:
Runs on linux
Has syntax highlighting for rails (.rhtml, .erb, .rake, etc.)
Is lightweight (not only the look and feel but also I don't want it generating all the unnecessary baggage that IDEs do)
Provides the basic features that pretty much all text editors do (I know this sounds vague and stupid but to be more specific all text editors should give you the option to specify the encoding, replace tabs with spaces, specify tab size, specify the default new line characters, etc. etc.)
Free. Open source is a nice to have but not a requirement.
Sublime Text 2 is an amazing text editor. You can use it for free but they show you a little nag-screen every know and then.
// Check out the packet management, too
// Here is Paul Irish demonstrating live linting and Zen Coding in Sublime
Also Gmate is nice. It's Gedit with a number of plugins which make it behave like textmate.
https://github.com/gmate/gmate
Now, in the Ruby community, the most popular editor is Vim which is hard to get started with, but once you get used to it you won't go back. It's light-weight, customizable, extendable, powerful and absolutely awesome.
Another popular one is, as #superlukas said, Sublime Text 2 which is good, but if you want to use it long term, you'll end up having to pay for it (it's distributed as a never-ending trial).
Sublime Text 2 is what you are looking for just put in the command line :
sudo add-apt-repository ppa:webupd8team/sublime-text-2.
sudo apt-get update && sudo apt-get install sublime-text.
Then it will be in usr/lib/sublime-text-2.You can then do your path configurations from there.
In addition to the other options mentioned ( vim/gvim, Sublime Text 2, and Gmate), take a look at Redcar.
It's an editor for Ruby, written in Ruby. It's actually quite nice, although I tend to use Sublime and vim more these days.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 12 years ago.
Getting ready to try out vim or emacs for rails development. Does one of these support rails development any better than the other? This is on windows if that matters.
Edit
I'm not looking for reasons why or why not to use vim or emacs and I don't want opinions on which is a better editor. I mainly just want to know if one or the other has more/better tools or plugins for using rails, or are they about the same?
Emacs is quite good with Rails when you include the rinari minor mode, and ruby-electric-mode (which comes with the Rails source) is also nice -- more here. That said, it is a bit of a struggle to set up and the learning curve is steep.
Recently (few months ago) I've switched from RubyMine (around €90) to VIM (exactly €0) and I'm really happy with that.
It's not easy to describe why it's better but one thing I love about VIM is that I don't need mouse anymore. It probably sounds funny but I feel much happier without a mouse - because it frees me from the table.
In VIM you'll find helluva lot of nice features - just google around. For example one of the best is ci" which will delete all text inside " and you can start writing. But there are many many others.
The full blown IDE's are IMHO useless for Ruby and other dynamic languages. Their best features like: refactoring, code completition, syntax checking, etc. simply doesn't work. Or worst - works on 80% percent. And they will never work as Rails are full of eval(some_text_that_generates_methods)
I can't speak for Emacs as I've never used it.
I'm not sure how is it on Windows platform as I'm on Mac/Linux. But it should be similar.
UPDATE: Ah, I forgot to provide a link to nice VIM setup for Ruby on Rails: http://github.com/akitaonrails/vimfiles
If you follow the README you will have a working environment ready in a minute. There are many useful plugins in this repository (git submodules to be exact) - just take a look inside.
Vim has rails.vim, a great plugin to help in Rails development. I'm not aware of anything comparable for Emacs. To get the feeling just take a look at the rails.vim screencast.
Although EMacs is a very very powerful tool, the learning curve is unbelievable huge (in my experience) and tends to be overkill for most needs. Running in windows, will also be a damper because you'll be switching from the two extremes - all command line and all gui. I think VIM is a great editor, and as pointed out, Yahuda Katz wrote about how he converted to Vim from textmate.
My vote's for Vim (It's what I use for Rails).
Don't be surprised if after a while in your windows programs and editors (e.g. Visual Studio and Notepad) you're trying to use your vim keystrokes.
I personally only use vim for editing configuration files, or when I need to program on a machine that's not mine. Try Eclipse with one of the plugins, like Aptana.
I don't know about Ruby, but emacs has more and better tools allover, autocomplete, syntax highlighting and general options editing is easier and prettier, and easier to writes plugins for, too. On the other hand, what's been said is true: it's a steeeeeeeeep learning curve, and overkill for most tasks.
Also, you should tag this question [holy-war]
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I have only little knowledge about LaTeX, basic formatting, basic math fomulae etc.. I found that LaTeX is hard to configure to my own flavor. Recently, I've heard about Docbook, which is also a typesetting mechanism, but much easier since it uses XML. So, if my main job using LaTeX/Docbook is writing a simple document (not a class book) with some mathematics, and I want easy configuration, and a highly constomizable application, which one is better, and is there any good book on Docbook?
DocBook isn't "a typesetting mechanism". DocBook is all about separating presentation from content. DocBook only deals with content; it's used to create an abstract representation of a book, article, etc. There are numerous tools out there which layout DocBook according to predefined templates. Some of these tools use LaTeX. AFAIK, O'Reilly uses a slightly modified version of the DocBook language to author their content, then they feed this XML into custom scripts that integrate with Adobe FrameMaker to layout their books.
LaTeX is essentially an attempt to separate presentation from content within TeX, but it doesn't quite achieve that goal IMO. Presentation is still mixed with the content in most cases. I think LaTeX is currently the best open source tool for laying-out paginated documents. However, proprietary tools like InDesign have many features (like good OpenType support) that TeX doesn't have (XeTeX kind of adds OpenType support). Either way, if you're writing a book, I highly recommend using DocBook to author your content rather than LaTeX.
That said, it sounds like you're writing short, one-off documents with a bit of math. I think LaTeX is probably your best choice. If you need lots of customizability, you might need to use Plain TeX as opposed to LaTeX, but it's going to require quite a bit of work on your part.
Well, I haven't used DocBook, but from a quick look on wikipedia and google:
DocBook does not have elements to describe mathematics.
DocBook is XML, as you say. To me, that makes it a horrible thing to write by-hand (or, rather, with a basic text editor). Maybe you enjoy writing XML, or have a good IDE. I guess you could look at this question.
DocBook's Wikipedia page lists a couple of books on it which you may want to look at, though I obviously can't say whether they are "good" books.
I would suggest going with LaTeX. Get someone to give you a basic template, then writing LaTeX is as simple as:
\section{Introduction}
This is my introduction.
\section{Stuff}
Here is some stuff.
\subsection{Particular stuff}
A particular type of stuff. With maths:
$\int_{x=1}^n 3x^2$
% etc.
Google is your friend for finding basic templates that you can start from:
One
Two
Three
To go from source code to a document, you'll need a working install of LaTeX (which is beyond the scope of this answer, but is pretty easy if you're on linux). Ideally your LaTeX install will include pdflatex. Then you just run:
pdflatex source.tex
(there's a bit more work if you have a bibliography – but that's a topic for a different question)
The great thing about DocBook is that it is XML based - so a chapter is a full subtree, a section is a full subtree, etc. In LaTeX, separation is only determined by the structure of the document during a linear scan.
The worst thing about Docbook is that it is XML based - lower-level stuff is extremely dirty and annoying to code manually.
I'm not really familiar with DocBook, though I have used LaTeX fairly extensively. The idea of LaTeX is not to produce a customized document, it's to produce a readable, attractive document. It's a set of libraries, templates, macros, and so forth around TeX, set up by people who know what they are doing when it comes to document design. Of course, you have special needs that they can't anticipate, so you're going to have to do some tweaking, too. It is a very high-level, declarative language that is meant to reflect the content and structure of a document, rather than what it should look like, the idea being that your ideas and how they are organized is what you should concern yourself with, not the layout of your text on the page. If you need more control, there exists a HUGE library of additional styles and macros and so forth (CTAN), and some of them (memoir comes to mind) give you back a lot of that control.
If you are shoving a lot of complicated formatting stuff into the body of your LaTeX document, you're doing it wrong. What you need to do is get your content in there, and your document structured into chapters and sections and subsections semantically, then go back in and worry about formatting. You shouldn't have to go into the body of your document much at this point; it should all be general stuff that applies to the whole document, preferably in a reusable way. This ensures consistency.
Yes, LaTeX is kind of difficult to configure to produce exactly the kind of layout you want. I suggest you take a look at the manual of the LaTeX class memoir to see what kinds of layouts it enables you to produce.
There is a book on DocBook available online. Take a look at that too, to see what kind of layouts you can produce and if you can easily format the math content you want with DocBook.
My suggestion is to go with LaTeX if you have to write any nontrivial math, but of course it depends on which format you find it easier to work with.
About two years ago, I tried to like and use DocBook; however, I returned to LaTeX because, at least at the time, LaTeX produced better quality output (PDFs). I never managed to get the DocBook to LaTeX to PDF translation working. My problems were likely "operator error", but I suggest trying DocBook (and LaTeX) for a few simple documents before choosing one.
Here are a few points that led me to choose LaTeX:
BibTeX for bibliographies with JabREF as a GUI
Excellent quality PDF output
Lots of examples on the Internet, including several similar to my preferred format
Good books, like "A Guide to LaTeX"
If you like GUIs, take a look at LyX.
The real reasons to use DocBook center on having your document marked up meaningfully, being able to validate it, and transform it for many purposes, not only publishing. LaTeX and other macro sets add a layer of semantic markup, but you're always free to introduce TeX code, and add macros from other sources. Fundamentally, a TeX document is a computer program that can only be parsed by a TeX processor.
For maths and DocBook: DocBook being XML it allows you to use other XML technologies as appropriate; in this case MathML. The XMLmind XMLEditor already mentioned provides a GUI maths editor, and includes stylesheets to format them for web and print along with the DocBook contents.
There are also tools available that enable translation of XML documents into other languages (xml2po is a simple one, http://heartsome.net/EN/home.html is a whole suite).
I don't want to go down the "easier" or better route as I regard this as a matter of taste and getting used to. I see docbook being XML as an advantage as therefore it can be morphed into almost anything you like by using XSLT. Combined with its self-containedness it feels more like structuring content that Latex does. Especially documenting open source software Docbook is really widely used. You can easily grab the templates and stylesheets of e.g. Hibernate and/or Spring and tweak them to your needs.
Another aspect I'd like to spot on is integration in build systems. For Maven there is a plugin called docbkx available, that just spits out PDF, HTML and whatever you like based on the contents and an appropriate XSLT. No further installations needed. The only ways I have seen to get this done with Latex is installing a few packages to the build OS and building your own script around em. IMHO that's not a feasible way to go, especially if you build cross platform.
Regarding the editor I can advise XMLmind XMLEditor that takes a lot of the pain and provides quite a nice WYSIWYG approach to docbook.
If you rely on mathematical expressions I also would rather choose Latex as there is nothing with the same power available in docbook.
FWIW I use docbook via xmlmind (http://xmlmind.com/) to produce html and .chm files. I've also set fop up to produce pdfs, but they aren't pretty.
Having got the docbook source done, I cook it with xsltproc and the docbook.xsl files. This is protracted and painful to set up, but once it's working it's sweet.
Another approach would be to use pandoc (an extended markdown type tool) to get from markdown to DocBook. This would cut the xml editor out, but you still have to do the transformation(s) to your output format.
Whoever had to create a professional, scientific document (research paper, book, technical guide etc.) will know why TeX is a better choice.
For those who are not aware of some facts here is a perfect example: at good colleges student's work may be completely refused if (s)he did not properly reference other people's works. There are, I believe, hundreds of "official" ways for citing and referencing, Harvard school has its own, ACM their own, among computer scientists numeric (Vancouver) notation is the most common. Many professional organisations have their own styles, and they stick to it. As far as I know, TeX is the only typesetting system that is aware of that, and with the help of BiBTeX it becomes extremely powerful tool for authors. It can save hours, if not days, of work.
If I was a novel writer, or author of some non-technical document, I might chose DocBook.
Have you looked at ConTeXt. It is more flexible and much easier to configure compared to LaTeX.
Arbortext supports native LaTeX. You can send the publishing engine or print composer LaTeX and it'll pass it through. It also supports a lot of other composition languages as well.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I have many small files containing code fragments, pseudo-code algorithms, classes, templates, SQL-samples, etc., and I obviously cannot put all these into libraries. I need a practical method to index all of them, and to be able to make this index available to others.
What must such an index contain to
make searching easiest?
Are there any such repositories
available on the web? (So I can test
the techniques they use.)
Are there any applications already
written that implement this that I
can have a look at?
Possible duplicate: https://stackoverflow.com/q/90300/15161
If you're working with .NET / Visual Studio, you could look at adding them as code snippets
Code Keep is a pretty good online repo for CodeSnippets and has plugins for VS2008
What we've done at work is created a common account for the dev to use, so everyone submits to codekeep under a common login and then can retrieve everyone elses snippets.
Also it might be worth your while creating a developer wiki on your dev network. Somewhere that the old hands can leave documentation on your regularly used patterns & snippets and new team members can check for help. We use TRAC in house as an all in one WIKI / Issue Management / SVN Integration and it does the job nicely
Another similar result from searching StackOverflow: Best Application For Storing Code Snippets
You might want to try refactormycode.com or set up your own wiki for it. A wiki actually sounds like a good application here.
I find the only way to manage source code is in the source control repository. This includes templates and pseudo code algorithms.
How it's different from the rest of your code ?
I'm familiar with cvs that can be hosted for example here (setting up cvs server is not to complex task either) you can search the repository using cvsearch and browse it using cvs web client.
I'm not saying cvs is a best option just another one that fulfill all your need.
Code snippets is a not a good option, IMHO.
You can do a full-text index of your hard drive using a tool like Copernic, Windows Live Search, or Google Desktop. Then whenever you want a code snippet that does a specific thing, just search for the relevant keywords and there it goes.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 9 years ago.
What Delphi coding standards document(s) do you follow?
Our company is looking at putting some better coding standards in place, to improve our code’s readability, reviewability, and maintainability. We’ve come across CodeGear’s “Object Pascal Style Guide”, but it hasn’t been touched in quite a while and I imagine a number of people have made some local improvements or additions. I’ve come across some published variations and other documents, which I will list, below.
NB: I do not want to start a style war. I just want to know what standards you follow, and why.
Thanks.
UPDATE: Well, the "JCL Delphi Language Style Guide" seems to be the clear winner! Thanks!
Project JEDI Delphi Language Style Guide With JCL Additions
(An extension of CodeGear’s “Object Pascal Style Guide”)
https://wiki.delphi-jedi.org/wiki/Project_JEDI_Delphi_Language_Style_Guide
(Thanks to Jeroen Pluimers and AmigoJack for reporting that the old links had died.
And in case this latest link also dies, here's its Internet Archive link, for good measure.)
CodeGear’s “Object Pascal Style Guide”
http://edn.embarcadero.com/article/10280
Econos – Coding Standard Document
(Subtitled “Delphi 4 Developer's Guide Coding Standards Document”.)
http://www.econos.de/delphi/cs.html
About.com’s “Delphi Identifier Naming Conventions”
http://delphi.about.com/od/standards/l/bldnc.htm (via Wayback Machine)
It really doesn't matter as long as you pick one and stick to it. A coding standard is like a dialect, and as long as everyone on the team speaks the same dialect, you're fine.
That said, why not pick the same standard as your runtime library (VCL) and documentation use? Then you will all be speaking the same dialect and you will have an easier time reading the runtime library code. And there are plenty of code examples to illustrate coding conventions.
There can be a tendency to over-engineer coding standards to the point where they get in the way of writing code.
I agree with Jozz’s comment. You can look at all the recommended standards, pick one and force it upon your coders or you can get your team involved in the process.
In my experience, the best way to get a team engaged is to have the team come up with the idea and the benefits of adoption. Your existing talent is your best resource. Likewise, they can be your ultimate enemy if you force them down a path they don’t buy into.
So, take a look at your existing coding variants and get the team together for some vibrant discussions on:
The reasons for adopting a coding standard.
Essential considerations in standardization.
Surfacing any insecurities in the team surrounding this issue.
Finding a point of agreement. What's important and what's not.
Establishing some corporate objectives so everyone feels like they are working towards a common goal.
Get the team to sell the benefits of standardization to themselves.
The most important objective must be to establish a ‘standard’ that best serves your team and your company.
For some inane historical reason, the coding standard at my work is to have all keywords in uppercase, in both delphi and sql. Thank god for caps lock.
CodeGear’s “Hungarian peanut butter”, for naming identifiers
http://dn.codegear.com/article/27983