I have multiple single sequence diagrams.
most of them have the same initialization and termination sequence.
It is possible to copy this from one file to the other but it would be much better if this part could be declared at a single point. So in case of a change it would not be necessary to change all the diagrams.
Is there a way to do this ?
I tried to comment to JRI's answer but I don't have a high enough reputation.
I found that !include works until you need to include the same file multiple times. I got a solution on a plantuml forum and I can't remember the forum but I do remember the solution. On the second and each additional time you include a file you want to use !include_many.
Yes, you should use a reference fragment to reference the separate initialization / termination sequences:
#startuml
participant Alice
participant Bob
ref over Alice, Bob : initialization
Alice -> Bob : hello
ref over Alice, Bob : termination
#enduml
If you want to show the detail of the re-used parts, rather than abstract them away as a reference block, PlantUML allows you to include files using the !include or !includeurl directives.
The syntax also allows you to import particular blocks of code from an imported file. See http://plantuml.com/preprocessing for details.
#user349062 comment is the correct answer. This was not easy to find, and its not in the documentation: Reference Guide
Using !include_many instead of !include in subsequent pages works, which doesn't make much sense, but there you go.
Related
I am trying to implement some quantum error correcting codes in Liquid (please correct the tag if need be), and I thought I'd start by reproducing the Steane7 class discussed in the User's Manual here starting on page 55 (page 56 of the pdf). I have a couple of questions about the provided code though.
The overall structure of the file is unclear to me. The example starts out by defining "type Steane7". This is a class definition, so I assume all of the following code is indented under this? On page 58 (59), it makes a reference to going back to the class definition to add the overrides, which makes it seem like the above code is not indented under the type. I assume this is meant to me that it's indented under the type but not under the synd method?
In the previous mentioned overrides on page 58 (59), what is s and where does it come from? In F#, one can use words other than "this" and "self". Is that what s is supposed to be here, or is s referring to a value previously defined but not mentioned?
The drawing instructions in the prep gate on page 56 (57) say "Error! Hyperlink reference not valid." What are the proper drawing instructions here? I'm guessing that's supposed to read "\multigate{#%d}{%s}"?
The method "fix" has an else with no if on page 58. What's the proper reference to the parent here?
Are there any pieces of the Steane7 class missing from the User Manual? If I call this in a script, it's going to work exactly like the compiled version of the code?
For future codes I implement, are there any other methods which should be overridden? I am piecing together the QECC class by inspecting the compiled assembly through VS.
Frankly, all of these questions could be answered by someone simply pointing me to the source code for QECC and Steane7. The "source" folder I grabbed from the GitHub only has precompiled executables.
I just posted the source for Steane7 to the Liquid GitHub repo. I hope that helps!
I'm currently working on a project, which has to be MISRA 2012 compliant. But in the embedded world, you can't fulfill every MISRA rule. So I have to suppress some messages generated by QA-C. What's he best solution to do this?
I was thinking about making a table in every module header file with references (\ref and \anchor) to the relevant code lines, a description, etc. The first problem is: I can't use the Doxygen markdown table feature, because then the description has to be in one line, because Doxygen tables don't support line breaking. So I thought about using a simple verbatim table, what do you think?
Or is there a way to generate such a table automatically?
Greetings
m0nKeY
According to MISRA, all such undesired rules must be handled by your deviation procedure, given that they are either "required" or "advisory". You are not allowed to deviate from "mandatory" rules. (Strictly speaking, you don't need to invoke the deviation procedure for advisory rules.)
In my experience, the safest and smoothest way by far to do this, is to not allow individual deviations on case-by-case basis. All deviations from MISRA should be stated in your company coding standard, and in order to deviate you have to update that document. Which in turn enforces approval from the document owner, who is preferably the most hardened C veteran you have in the team.
That way, you prevent less experienced team members from misinterpreting the rules and ignoring important rules, simply because they don't understand them and mistake them for false positives. There should be a rationale in the document stating why the rule you deviate from is not feasible for your company.
This means that everyone in the dev team is allowed to deviate from the listed rules at any point, without the need to invoke any form of bureaucracy.
Once you have a setup like this, simply customize your static analyser and remove/ignore the undesired warnings. That way, you get rid of a lot of noise and false warnings from the tool.
To answer your question generally: To create an aggregate occurrence list of anything in doxygen, use \xrefitem
We use this as a tool in our code review process. I tag code with a custom tag \reviewme which adds the function to a list of all code in need of peer review. The next guy can come along and clear that tag. We have another custom tag \reviewedby which does not use \xrefitem but simply puts the reivewers name and the date in the code block saying who reviewed it and when. This had gotten a bit clunky as things have scaled with larget code bases and more developers. Now we're looking into tools that integrate with our version control process to handle this better. But when we started this it worked well and fit a shoestring budget. But that example should give you an idea of is capable.
Here is a screen shot of what the output looks like - proprietary stuff and auto names redacted:
Here is how we added this custom tag as an alias to xrefitem in our doxy file as follows
ALIASES = "reviewme = \xrefitem reviewme \"This section needs peer review\" \"Documentation block or code sections that need peer review\""
To add it from the GUI, you would go to Expert->Project->Aliases and add a line like this
reviewme = \xrefitem reviewme "This section needs peer review" "Documentation block or code sections that need peer review"
Same thing, just no need to put quotes around the whole thing and escape out the inner quotes.
\xrefitem is the underpinning of how things like \todo or \bug work in doxygen. You can make a list of just about anything your heart desires.
Speaking specifically to MISRA exceptions: Lundin's post has lot's of merit. I would consider it. I think a better place to document exceptions to coding standards is in the static analysis tool its self. Many tools have their own annotations where you can categorize the rule violation as 'excused' or whatever. But generally this does not remove them from the list, it allows you just to filter or sort them. Perhaps you can use REGEX in a script that runs prior to doxygen that will replace the tool specific annotation with a custom \xrefitem if you are really concerned. Or vice vera, replace the doxy annotation with your tool's annotation.
question is related to Using Doxygen with C, do you comment the function prototype or the definition? Or both? .
doxygen formatting makes the declaration and its comments from my .h file appear first, followed by the definition and its comments from my .c file. good.
alas, is there some parameter like \param[in] or \return[in] that I can use just before the .c definition for the html output to indicate visually "now I am describing implementation"? It could put a boldface on the left, or even change the color to set it off visually. The obvious \implements tag does not do this.
I looked at the generated doxygen html code, and there is no obvious css class to change. so I presumably should use a tag from http://www.doxygen.nl/manual/commands.html . what do others use?
One option, which is not ideal but does have the merit of simplicity, is to use the \note command.
Prefixing the paragraphs describing the implementation with \note will result in them showing in the output with a green'y-yellow sidebar. You could change the color in the CSS. Subsequent \note paragraphs will remain as separate paragraphs but have a single heading and sidebar.
The downside is that the section is headed Note:. This may or may not be acceptable for your needs.
You could use \xrefitem instead, which would allow you to change the text to Implementation:, but it, quite reasonably, also generates an entry on a separate cross-reference page - which is probably not desirable. There may be a way of disabling the cross-indexing, but there's nothing in the manual about it.
I assume you are generating a document that is for internal use only; some form of Technical Manual perhaps? In which case, the 'Note' option may be the quickest and simplest solution.
Edit: I've just found the \remark command. Essentially equivalent to \note without a sidebar, but the associated heading Remarks may suit your application better. Chances are you can add the sidebar in the CSS.
I want to use joe or jed to code in C language. Any way to have autocompletion?
joe and jed are two completely different programs, but the answer is "not really" for both:
jed: theoretically yes, but practically no. The home page claims that jed is "extensible in the C-like S-Lang language making the editor completely customizable". You might be able to hack in autocompletion this way, but it'd probably be more work than learning to use a better text editor.
joe's documentation claims that you can "complete word in edit buffer by hitting ESC Enter (uses other words in buffer for dictionary)". Which is something, but it's not full autocompletion.
Ok. In the last hours I have learned the following (Only for jed):
Checking at Guido Gonzato's excellent Quick Reference Guide. we found:
Completion is the automatic expansion of partially-typed words. If
your text contains the word frobnication', typingfro' followed by
M-/ (M-X dabbrev) will either expand the whole word, or cycle amongst
all possible completions.
It works for previously typed keywords.
A better autocompletion can be obtained through complete mode. you will need:
Installing modes from Jedmodes.
I run a website that allows users to write blog-post, I would really like to summarize the written content and use it to fill the <meta name="description".../>-tag for example.
What methods can I employ to automatically summarize/describe the contents of user generated content?
Are there any (preferably free) methods out there that have solved this problem?
(I've seen other websites just copy the first 100 or so words but this strikes me as a sub-optimal solution.)
Think of the task of summarization as a challenge to 'select the most important sentences' from the document.
The method described in The Automatic Creation of Literature Abstracts by H.P. Luhn (1958) describes a naive method that actually performs quite well. Try giving it a shot.
If your website is in Python coding this algorithm using the NLTK (Natural Language Toolkit) is a fun task.
Make it predictable.
From a users perspective simply using the first paragraph is not bad at all.
Using any automation is bound to fall flat in some cases. So I suggest to display
the first paragraph (maybe truncating at some point) as a summary and offer the ability to override that by an optional field.
I might try using mechanical Turk or any number of other crowdsourcing options.
Another item to check out, a SourceForge project, AutoSummary Semantic Analysis Engine
Not a trivial task... You should look for articles or books on "extractive summarization"
A few starters could be:
Books:
Natural Language Processing with Python
Foundations of Statistical Natural Language Processing
Articles:
Language independent extractive summarization
Extractive summarization: how to identify the gist of a text
Extractive Summarization using Inter- and Intra- Event Relevance
Yahoo has a free API for this:
http://developer.yahoo.com/search/content/V1/termExtraction.html
Apple's patent 6424362 - Auto-summary of document content contains sample code which might be useful...
This borders on artificial intelligence so there's not going to be an "easy" solution out there, but there are products that target this problem.
Check out Copernic Summarizer, for one.
Noun phrases typically tend to be important elements of a sentence. Picking sentence(s) with a high density of noun phrases could yield a good summary. You could get noun phrases using a POS tagger.
For a good summary, it is desirable that it is a meaningful sentence. Reading a broken sentence is slightly jarring.
Alternatively, when the author posts the article, the author can highlight what are the keywords that can be used in the description which can then be automatically put in the meta description tag.