This is intended as a quick reference and showcase. For more complete info, see and the.Note that there is also a if that's what you're looking for.
Jupyter Notebook Users Manual. When you use a a markup language, your input does not necessarily exactly equal your output. For example, if I type '#Header 1' at the beginning of a cell, but then press Shift-Enter (or click the play button at the top of the window), this notebook will turn my input into a somewhat different output in the.
You can also check out.Table of ContentsHeaders # H1## H2### H3#### H4##### H5###### H6Alternatively, for H1 and H2, an underline-ish style:Alt-H1Alt-H2-H1H2H3H4H5H6Alternatively, for H1 and H2, an underline-ish style:Alt-H1Alt-H2Emphasis Emphasis, aka italics, with.asterisks. or underscores.Strong emphasis, aka bold, with.asterisks. or underscores.Combined emphasis with.asterisks and underscores.Strikethrough uses two tildes. Scratch this.Emphasis, aka italics, with asterisks or underscores.Strong emphasis, aka bold, with asterisks or underscores.Combined emphasis with asterisks and underscores.Strikethrough uses two tildes. Scratch this.Lists(In this example, leading and trailing spaces are shown with with dots: ⋅) 1. First ordered list item2.
Another item⋅⋅. Unordered sub-list.1.
Actual numbers don't matter, just that it's a number⋅⋅1. Ordered sub-list4. And another item.⋅⋅⋅You can have properly indented paragraphs within list items. S = 'Python syntax highlighting ' print s No language indicated, so no syntax highlighting in Markdown Here (varies on Github).But let's throw in a tag.TablesTables aren't part of the core Markdown spec, but they are part of GFM and Markdown Here supports them.
They are an easy way of adding tables to your email - a task that would otherwise require copy-pasting from another application. Colons can be used to align columns. Tables Are Cool - :-: -: col 3 is right-aligned $1600 col 2 is centered $12 zebra stripes are neat $1 There must be at least 3 dashes separating each header cell.The outer pipes ( ) are optional, and you don't need to make theraw Markdown line up prettily.
You can also use inline Markdown.Markdown Less Pretty- - -.Still. `renders`.nicely.1 2 3Colons can be used to align columns. TablesAreCoolcol 3 isright-aligned$1600col 2 iscentered$12zebra stripesare neat$1There must be at least 3 dashes separating each header cell. The outer pipes ( ) are optional, and you don't need to make the raw Markdown line up prettily. You can also use inline Markdown. MarkdownLessPrettyStillrendersnicely123Blockquotes Blockquotes are very handy in email to emulate reply text. This line is part of the same quote.Quote break.
This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can.put.Markdown. into a blockquote.Blockquotes are very handy in email to emulate reply text.This line is part of the same quote.Quote break.This is a very long line that will still be quoted properly when it wraps. Oh boy let's keep writing to make sure this is long enough to actually wrap for everyone.
Oh, you can put Markdown into a blockquote.Inline HTMLYou can also use raw HTML in your Markdown, and it'll mostly work pretty well. Definition listIs something people use sometimes.Markdown in HTMLDoes.not. work.very. well. Use HTML tags.Definition list Is something people use sometimes.
Markdown in HTML Does.not. work.very. well. Use HTML tags.Horizontal Rule Three or more.-Hyphens.AsterisksUnderscoresThree or more.HyphensAsterisksUnderscoresLine BreaksMy basic recommendation for learning how line breaks work is to experiment and discover - hit once (i.e., insert one newline), then hit it twice (i.e., insert two newlines), see what happens. You'll soon learn to get what you want.
Technical Publishing Software - Views on and Its AlternativesI've done spec documents with LaTeX and Framemaker, and designed a Framemaker workflow to support a team of 5 analysts producing a spec document for an insurance underwriting system. The document was expected to get to 2,000 pages or so. Many years ago (around 1992-1993) I also worked briefly as a typesetter.Framemaker is designed for technical documentation and does it very well indeed.
It also has features designed to support very large documents with multiple authors - people use this system to do documents with more than 100,000 pages. It is also more accessible than LaTeX to users familiar with word processing software.Key features of Framemaker:.Documents consisting of multiplefiles: You can pull together a'Book' with multiple subsections indifferent files. The document canalso be kept in source control.Textual MIF format forimport/export: The importer issomewhat finicky (I found generatingworking LaTeX to be easier) but you cangenerate items such as datadictionaries and import them intothe document. The file has textualanchors (see below) so you cancreate cross-reference links thatwill be stable across imports. Ifind this to be a key feature forspecs as it allows cross-referencesto link directly to generated items.Powerful tagging, indexing and cross-referencing System: Everythingis based on tags in Framemaker andit is easy to apply tags quickly.This means that cross-referencing,indexing, conditional text andapplying styles en-masse is easy andjust works. You can generate indexes and TOCs based on tags, sohaving multiple specialised indexes(such as a list of data field namesfrom screens or a data dictionary)is easy to do.
The document Idescribed above had 4 separateindexes.Stable: Framemaker is designed forprofessionals so it doesn't secondguess you in the way that word does.It is also much more stable on largedocuments. Anyone who's tried towrite a document of more than 50-100pages on Word should have a prettyfair idea of what this implies.Scriptable: FM has a C API and thereare various scripting plugins( andbeing probably the most widely used)which can be used to automate jobsin FM. Adds supportfor a Javascript based scripting toolcalled, presumablyported across from the scripting facilityin InDesign.Single-sourcing: From a single FMdocument you can produce PDF,Windows Help (CHM), HTML and printdocuments fairly easily. Thecross-references also resolve tohyperlinks.Global style controls: You caneasily set up styles for a documentand apply it across the wholedocument. It also facilitatesrunning headers and footers with agreat deal of flexibility in havingthem track sections, versions,chapters etc.Alternatives to Framemaker.LaTeX/Lout: You've already indicatedthat you don't want a markuplanaguage, but the andsystems are used for largestructured documents and do thiswell.Probably theonly real alternative to Framemakerif you want that sort of user interfacewithout paying bodily parts for theprivilege.It has strong support for structureddocuments and an XML-based documentinterchange format.
It's now ownedby Corel, who still appear to be actively promoting it.There are a couple of other technical publishing tools on the market: (which used to be known as ). These two are powerful tools - Interleaf used to be the market leader in this field at one point - but quite expensive.Although Adobeclaim you can do large documentswith InDesign, the cross-referencingand other large document featurestend to be viewed as lacking byFramemaker afficionados. There is,however, a text entry system for itcalled that apparentlydoes have this sort offunctionality and quitea large body of, some of which dosupport tagging and other such facilities.InDesign also has a scripting API anda JavaScript interpreter for executingscripts.I haven't used Indesign,so I can't really comment on howwell it works in practice.This is really justa standard format for structureddocuments but has a large ecosystemof tools surrounding it for writingand rendering documents. If youdon't want to use LaTeX you willprobably not want to use DocBook forsimilar reasons. Aspoints out (+1), goes to a StackOverflowpost from someone describing usingDocBook in practice.I've never really used DocBook and I'vemade so many edits to this post that it's now in Wiki mode, sosomeone familiar with DocBook mightwant to elaborate on this.Word processing software:has serious shortcomings as atechnical publishing tool and is notrecommended. Hassomewhat better structureddocumentation functionality thanword and may be a better choice ifpolitics or requirement to use.docas a document interchange formatpreclude a better alternative.is alsoconsiderably better fordocumentation-in-the-large than wordand still has a presence in several vertical marketssuch as legal offices.and: Theseare new kids on the block and livein roughly the same space asFramemaker.
The company was founded by formereHelp (creators of RoboHelp) employees and isactively developing, with multiple releases yearly. Theirofferings have greatly expanded in the past two years,to the detriment of the quality of the individual products.It seems focus has been on turning out new products andby consequence there are a lot of 'fit and finish' issues ineach. The authors have chosen to reinvent the wheel in many ways,resulting in confusing and often broken implementations. Save often,you will encounter unhandled exceptions.
Source control integrationis flaky. For example, moving or deleting a group of files will result inone source control commit for each file deletion. Big PITA whenyou have source control email notifications. Hello 500 emails.Flare can import Word and Framemaker files, but the importis far from seamless. Expect to retain all of your contentbut plan on completely re-styling from scratch.Flare shares many of Word's tendancies to do too much behindthe scenes and assume what the user would choose.
The HTML lookslike what Word outputs when you export HTML - lots of custom tagsand attributes, deeply nested inline styles, etc. The texteditor is maddening, for example, its cursor model is differentthan any other software you've ever used.Framemaker vs.
LaTeXThese two are main systems I have used to produce large, presentable system documents and I've had good results with both.Ease of Learning: TeX can give you absolute control but actuallyachieving this on a complex LaTeXdocument without breaking otheritems isn't trivial, particularlywhere a large number of macropackages are involved. Basic LaTeXisn't hard to learn, but makingmodified versions of.sty files thatstill work takes a bit of tinkeringif you're not a really deep TeXhacker. It can be done but beprepared to spend quite a lot oftime fiddling.Framemaker can give you a good degree of control on the look of the document and isn't that hard to learn.
Getting a house style and tweaking the layout (which you probably will have to do) will be easier with Framemaker.Ease of Text Entry: You can use tools such as to provide awordprocessor-like front end toLaTeX, and these work well if youwant to write large bodies of text.Framemaker's DTP-like user interfaceworks in a way familiar to peoplewho are used to wordproessingsoftware. From this perspectivethere is little practicaldifference.Templating Document Structure: Framemaker allows a documentstructure to be defined in terms oftags or an XML schema (if usingStructured Framemaker). LaTeX has aset of canned structural elementsthat are flexible enough to beuseful. Adding additionalstructural elements (e.g. A datadictionary item) can be done as amacro, but making them auto-numberis a bit more challenging and you willneed to poke around behind thescenes.
Both can do it, but it'sconsiderably more technical to do itin LaTeX in anything but trivialcases.Also, LaTeX does not havethe facility to template thedocument structure in the way thatStructured Framemaker does.However, you can achieve this typeof effect with DocBook and thengenerate to LaTeX if desired.Ease of Integration: I found making a generator for non-triviallycomplex MIF files to be quitefiddly. The MIF parser is quitepernickety in FM and doesn't reallygive good diagnostics. LaTeXproduces far better error messagesand is quite a bit less fussy.Technical Publishing Software vs.
Layout SoftwarePage layout software started with and the other main players in this space were its competitor and now InDesign, with which Adobe is essentially trying to deprecate and replace it and Framemaker., which you mentioned before, lives in the same space as these products.If you are producing a manual with less than (say) 50-100 pages, one of the packages would probably do an adequate job. They are really designed for advertising and layout-heavy publication tasks such as magazines, so their support for large-document features of the sort found in Framemaker is fairly limited. The key issue with these products is scalability - they do not work well on large documents.Just for reference I have actually typeset a 200-page book (someone's autobiography) using Pagemaker. While the fine-grained kerning and leading control helps a bit for copyfitting, it is still a highly manual process to lay out a book sized document. In this case the book was just straight text with no significant cross-referencing or structure other than chapters.
Doing a complex technical spec document or manual this size with Pagemaker would have been very fiddly and probably next to impossible to get right without any mistakes.Technical Publishing vs. Word Processing SoftwareThis is more of a description of key shortcomings of MS-Word for large spec documents. However, it will illustrate some of the main features required for documentation-in-the-large:.Indexing and Cross-Referencing: This is a real chore in Word, andquite unstable. Framemaker'stagging features and LaTeX's labelsmean that you can assign a tag orknown label (in a predictable formatif necessary).
The textual formatfor the tag anchors is exposed inthe user interface, and is used forthe linkage. In Word, the anchorsare much more opaque and noteasily controllable in this way.Combined with the clumsy userinterface and instability of theproduct, this makes maintainingthese fiddly, and often unstable -you often have to manually fix themup.Templated Layouts: Style support in word are quite basic andnumbering tends to be somewhatunstable. FrameMaker is all aboutdriving from the tags and applyingstyles based on the tags. Globalstyle changes just work inFramemaker in a way that they do notin Word.Large multi-file Documents: I've never been able to make this workwell in Word, but it is a keyfeature in Framemaker and LaTeX.Again, Word's instability means thatyou tend to spend a lot of timetidying up after it.
As thedocument grows larger, theproportion of time spent on thiswork grows quadratically -propensity for breakage proportionalto n (size of document). time tofix proportional to size n (timeto fix).Why is Word so Unstable: Word does a lot behind the scenes tosupport novice users and intervenein layouts.
It is also not reallyframe-based (text flow conceptuallyseparate from document layout), butthe developers try to implementvarious frame-like behaviours in the UI. Second-guesses you on acomplex document it often does thewrong thing. Framemaker 'treats theuser as an adult' and does none ofthis so things stay where you putthem.Other word processors such asOpen Office and WordPerfect do notmisbehave in quite the same way asWord, which is one of the reasonsthat just about any wordprocessor other than Word will do abetter job of technical documents.Pre-Flighting: In documentation-speak, this is theprocess of checking that yourassemblage of files for the document(image files etc.) is correct beforecommitting to print. Theprofessional systems will complainabout things that are wrong, givingyou a chance to correct it. Wordwill just put on a happy face andtry to fix things behind the scenes.A good example of this is a wordfile with linked graphics. If youcopy the file and graphics toanother directory and update one ofthe graphics in situ, word may wellstill read the file from the oldpath (I've seen it do this) and notthe new one you've just updated.However, this behaviour is not consistent andtypifies the rampant abuse ofunstable heuristics in that product.Pre-Press Support: A publishing system extends into the pre-pressphase of the workflow. This meansit covers preparation for print.Word processing software tends notto have this functionality or haveit in a very limited form.Without getting too far into this, a key difference is that publishing software tends to treat you like a consenting adult and not get in the way when you want to scale or automate things.
One can use word processing software for large scale documentation but it has many design decisions adapted to casual users writing short documents with little regard for quality. These adaptations come at the expense of fitness-for-task on large scale document preparation work. The main issues I find with Word for spec documents are the poor indexing and cross-referencing and general instability issues where I am always having to go back and fix things. However, political considerations in most environments (I'm a contractor) mean one is often stuck with it.Some general comments on the state of technical documentation softwareFramemaker would be the obvious choice if Adobe didn't keep giving off signals that they are trying to deprecate it and move its user base to InDesign. However, FM is widely used in aerospace, software and engineering circles and Adobe's management would face a if they actually EOL'd the product without a credible migration path. From what one reads on the web, Adobe's acquisition of FM was driven by John Warnock, but he was ousted and FM became a victim of office politics. The net result is that it's been moved to maintenance mode and is quite stagnant.Ventura Publisher has also been relegated to a niche market to some extent, but at least Corel do not have two competing product lines in the way that Adobe do.
It is probably a passable substitute for FM and may be more politically acceptable to PHB types as it is marketed as a 'business publishing' system.Quicksilver and Arbortext both seem to be viable products, but are very expensive. I've not used either, so I can't really make any real judgement on their merits.The markup language systems are free and very powerful in many ways. Lout might be a bit easier to work with as it doesn't have quite the level of legacy baggage that LaTeX does. DocBook is also quite widely used and does have quite a bit of tool support.
These technologies put a significant squeeze on the 'geek' end of Framemaker's market share and do so on their merits - they have probably taken quite a chunk out of Adobe's profit margins over the years. I would not dismiss these technologies out of hand, but they will be harder to learn in practice.You might try evaluating InDesign and a selected set of plugins (concentrate on those for tagging and cross-ref/index management). Baby pals game.
Finally, some of the word processing software (Wordperfect and OpenOffice) give you a reasonable toolkit for structured documentation and work considerably better for this than MS-Word.PostScriptYes, that is a pun. I haven't touched on Pre-Press functionality of any of these products.
Printing and Pre-Press are technical fields in their own right and the scope for expensive mistakes means you should probably leave this up to specialists.Framemaker, InDesign, Ventura, QuickSilver, Arbortext and (presumably) the MadCap products all come with facilities to do pre-press preparation. By and large, word processing software does not.Doing pre-press with LaTeX tends to involve post-processing the PS output with software like or rendering to PDF and taking the pre-press workflow from there. Generally, most pre-press houses can work from PDF, so a good PDF writing tool like Distiller is the best interface for work prepared from tools that are not designed for prepress work. Note that the quality of the output from tends to be better than the based ones like.Note that the RGB colour space of a monitor does not have a direct map to a CYMK colour space used by a printing press. Actually getting colours - especially colour photos - to come out correctly on a press is somewhat fraught if you do not have the right kit. For print production, see a specialist unless you have reason to believe you know what you're doing.
For a casual user I would still recommend this 15 years after I was involved in the industry, as mistakes are very expensive to fix once they're committed to print.If you really do want to do colour print work in-house, you will probably need to your monitor. For best results, you should get a high-fidelity monitor like from HP. In order to calibrate the monitor you may also need a sensor like one of the ones described in if the monitor does not come with one. Most professional graphics cards like these from, or have facilities to support gamma correction; many consumer ones do as well.
You will also need to get calibration data for the press you are going to be using to print, although the pre-press house will probably be able to do this.As stated before, print media is quite technical in its own right, easy to get wrong and expensive to fix once it's gone to print. If you're not 100% certain you've got your calibration right, get a colour proof like a. This is done from the actual film separations (and is thus quite expensive), so it gives an accurate rendition of the actual colour of the final printed article.
Doing this for a few sample pages will give you accurate feedback about whether your calibration is set up right.Acknowledgements: Thanks to for expanding the section on Madcap products.