Re: handling description markup/semantics for SQLite3 "output"?
Travis Everett <[email protected]> Mon, 10 Jul 2017 12:46:53 -0500
| Newsgroups | gmane.text.doxygen.devel |
|---|---|
| Message-ID | <CAC=jSUXA7c7OFpC6kPVC5vf5AfX-T2L7Bjtu_99b8QHtmQnnNw@mail.gmail.com> |
--===============4223389731931153872== Content-Type: multipart/alternative; boundary="001a1137356a1e2c2d0553fa2b7e" --001a1137356a1e2c2d0553fa2b7e Content-Type: text/plain; charset="UTF-8" I think maybe we're talking past each other :) I'm already building out the `generateSqlite3ForPage` work-in-progress stub you created, and pages currently fit within the existing compounddef SQL table just as well as they fit within the compounddef XML schema. My question is whether/how the detaileddescription can be saved in a single format, so that it's not in at least 3 different formats. I noticed this problem while building out the "page" type (and used it as a succinct example of the issue), but it *already* exists for any fields that can hold arbitrary nested input (such as complex detaileddescriptions on memberdefs). I've added a 6th file at the end of the gist ( https://gist.github.com/abathur/b3d3d25885303eb216e0ffa2d2604034) containing the database row for one of our more complex member definitions, demonstrating this issue. This problem will apply to all additional compound types as I build them out. Hope this clarifies, T On Mon, Jul 10, 2017 at 11:05 AM, Adrian M Negreanu <[email protected]> wrote: > Hi, > I think, from the gist you posted, that your use case needs to extend the > current schema so that the elements you see in the xml will also be found > in sqlite3. > > So you'll need a `page` table and add a generateSqlite3ForPage that fills > in that table. > Tbis way the semantic you mentioned previously would be provided by the > new table/attribute. > > On Jul 10, 2017 18:57, "Travis Everett" <[email protected]> > wrote: > > Hi again Adrian, > > I agree with what you've said, but I think that only holds when the > detaileddescription database field holds a *single* format. > > An example of the input/output I'm working with might be more useful than > my initial description: https://gist.github.com/abathur/b3d3d25885303eb > 216e0ffa2d2604034 > > In this example, you can see that the string going into the database > contains three different formats: an HTML header, plaintext markup, and > Doxygen commands. > > Context: `generateSqlite3ForPage` is one of the parts of sqlite3gen that > I'm refining as I work on a broader project that generates Doxygen-ready > source files and markdown pages from a large Sphinx/RST corpus. > > Cheers, > Travis > > On Sun, Jul 9, 2017 at 11:48 PM, Adrian M Negreanu <[email protected]> > wrote: > >> Hi Travis, >> >> The format of the description is dictated by the client's needs. Or in >> other words, where that description is used. >> >> I'm using it from python scripts which makes it easy to parse the current >> plain text. >> >> This brings me to the question : why do you need another format, say (A), >> when you'll already have to parse the plaintext format to extract the >> semantic needed by (A) ? >> >> One reason for adding (A) is "it's easier for the client to use/parse", >> which brings me again, to the first part : what client do you have ? >> >> Regards >> >> >> On Jul 10, 2017 3:21 AM, "Travis Everett" <[email protected]> >> wrote: >> >> All, >> >> I'm resuming work on refining the experimental SQLite3 output. I've run >> into a pretty obvious quandary that I was blissfully ignorant of: >> >> Before output-format-specific conversion, it looks like detailed >> descriptions can include (at least) a mix of HTML and raw text that still >> contains doxygen commands (I haven't gone fishing, but my guess is that >> markdown gets translated down to HTML, and output translators are >> responsible for the rest). >> >> When it's being served by an SQL database, it doesn't seem like there's >> an "obvious" or "expected" format for presentational/semantic markup >> embedded in the detailed description. I was a bit surprised to find >> plaintext Doxygen commands present at this stage. >> >> I'm curious if anyone has thoughts on how to handle these. The best three >> paths forward seem to be: >> >> - Saving it as XML. I'm not keen on this since it significantly raises >> the bar on using the sql output, and would require either updating all of >> the descriptions in place, or parsing them into a more useful form on each >> use. >> - Saving an opinionated plaintext translation. This would retain simple >> usability and avoid the update-all-descriptions or constantly-reparse >> issues, as long as consumers can live with the format ;) >> - Some active, user-configurable translation method (probably translate >> to XML and then call a user-defined translator script as with input >> filters. *not sure how complex this would be or where to start; may be >> getting out of my depth. >> >> Thanks for any direction, >> Travis >> >> ------------------------------------------------------------ >> ------------------ >> Check out the vibrant tech community on one of the world's most >> engaging tech sites, Slashdot.org! http://sdm.link/slashdot >> _______________________________________________ >> Doxygen-develop mailing list >> [email protected] >> https://lists.sourceforge.net/lists/listinfo/doxygen-develop >> >> >> > > ------------------------------------------------------------ > ------------------ > Check out the vibrant tech community on one of the world's most > engaging tech sites, Slashdot.org! http://sdm.link/slashdot > _______________________________________________ > Doxygen-develop mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/doxygen-develop > > > --001a1137356a1e2c2d0553fa2b7e Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr">I think maybe we're talking past each other :)<div><br= ></div><div>I'm already building out the `<span style=3D"font-size:12.8= px">generateSqlite3ForPage` work-in-progress stub you created, and pages cu= rrently fit within the existing compounddef SQL table just as well as they = fit within the compounddef XML schema.</span></div><div><span style=3D"font= -size:12.8px"><br></span></div><div><span style=3D"font-size:12.8px">My que= stion is whether/how the detaileddescription can be saved in a single forma= t, so that it's not in at least 3 different formats.=C2=A0</span></div>= <div><span style=3D"font-size:12.8px"><br></span></div><div><span style=3D"= font-size:12.8px">I noticed this problem while building out the "page&= quot; type (and used it as a succinct example of the issue), but it <i>alre= ady</i> exists for any fields that can hold arbitrary nested input (such as= complex detaileddescriptions on memberdefs).=C2=A0</span><span style=3D"fo= nt-size:12.8px">I've added a 6th file at the end of the gist (</span><a= href=3D"https://gist.github.com/abathur/b3d3d25885303eb216e0ffa2d2604034">= https://gist.github.com/abathur/b3d3d25885303eb216e0ffa2d2604034</a>)=C2=A0= <span style=3D"font-size:12.8px">containing the database row for one of our= more complex member definitions, demonstrating this issue.=C2=A0</span><sp= an style=3D"font-size:12.8px">This problem will apply to all additional com= pound types as I build them out.=C2=A0</span></div><div><span style=3D"font= -size:12.8px"><br></span></div><div><span style=3D"font-size:12.8px">Hope t= his clarifies,</span></div><div><span style=3D"font-size:12.8px">T</span></= div></div><div class=3D"gmail_extra"><br><div class=3D"gmail_quote">On Mon,= Jul 10, 2017 at 11:05 AM, Adrian M Negreanu <span dir=3D"ltr"><<a href= =3D"mailto:[email protected]" target=3D"_blank">[email protected]</a>></sp= an> wrote:<br><blockquote class=3D"gmail_quote" style=3D"margin:0 0 0 .8ex;= border-left:1px #ccc solid;padding-left:1ex"><div dir=3D"auto">Hi,<div dir= =3D"auto">=C2=A0I think, from the gist you posted, that your use case needs= to extend the current schema so that the elements you see in the xml will = also be found in sqlite3.<br></div><div dir=3D"auto"><br></div><div dir=3D"= auto">So you'll need a `page` table and add a generateSqlite3ForPage th= at fills in that table.</div><div dir=3D"auto">Tbis way the semantic you me= ntioned previously would be provided by the new table/attribute.</div></div= ><div class=3D"HOEnZb"><div class=3D"h5"><div class=3D"gmail_extra"><br><di= v class=3D"gmail_quote">On Jul 10, 2017 18:57, "Travis Everett" &= lt;<a href=3D"mailto:[email protected]" target=3D"_blank">travis.a= [email protected]</a>> wrote:<br type=3D"attribution"><blockquote class= =3D"m_-6176303908850086807quote" style=3D"margin:0 0 0 .8ex;border-left:1px= #ccc solid;padding-left:1ex"><div class=3D"m_-6176303908850086807quoted-te= xt"><div dir=3D"ltr"><span style=3D"font-size:12.800000190734863px">Hi agai= n Adrian,=C2=A0</span><div style=3D"font-size:12.800000190734863px"><br></d= iv><div style=3D"font-size:12.800000190734863px">I agree with what you'= ve said, but I think that only holds when the detaileddescription database = field holds a=C2=A0<i>single</i>=C2=A0format.</div><div style=3D"font-size:= 12.800000190734863px"><br></div><div style=3D"font-size:12.800000190734863p= x">An example of the input/output I'm working with might be more useful= than my initial description:=C2=A0<a href=3D"https://gist.github.com/abath= ur/b3d3d25885303eb216e0ffa2d2604034" target=3D"_blank">https://gist.gith<wb= r>ub.com/abathur/b3d3d25885303eb<wbr>216e0ffa2d2604034</a></div><div style= =3D"font-size:12.800000190734863px"><br></div><div style=3D"font-size:12.80= 0000190734863px">In this example, you can see that the string going into th= e database contains three different formats: an HTML header, plaintext mark= up, and Doxygen commands.=C2=A0</div><div style=3D"font-size:12.80000019073= 4863px"><br></div><div style=3D"font-size:12.800000190734863px">Context: `g= enerateSqlite3ForPage` is one of the parts of sqlite3gen that I'm refin= ing as I work on a broader project that generates Doxygen-ready source file= s and markdown pages from a large Sphinx/RST corpus.=C2=A0</div><div style= =3D"font-size:12.800000190734863px"><br></div><div style=3D"font-size:12.80= 0000190734863px">Cheers,</div><div style=3D"font-size:12.800000190734863px"= >Travis</div></div></div><div class=3D"gmail_extra"><br><div class=3D"gmail= _quote"><div class=3D"m_-6176303908850086807quoted-text">On Sun, Jul 9, 201= 7 at 11:48 PM, Adrian M Negreanu <span dir=3D"ltr"><<a href=3D"mailto:gr= [email protected]" target=3D"_blank">[email protected]</a>></span> wrote:<br= ></div><div class=3D"m_-6176303908850086807elided-text"><blockquote class= =3D"gmail_quote" style=3D"margin:0 0 0 .8ex;border-left:1px #ccc solid;padd= ing-left:1ex"><div dir=3D"auto"><div>Hi Travis,</div><div dir=3D"auto"><br>= </div><div dir=3D"auto">The format of the description is dictated by the cl= ient's needs. Or in other words, where that description is used.</div><= div dir=3D"auto"><br></div><div dir=3D"auto">I'm using it from python s= cripts which makes it easy to parse the current plain text.</div><div dir= =3D"auto"><br></div><div dir=3D"auto">This brings me to the question : why = do you need another format, say (A), when you'll already have to parse = the plaintext format to extract the semantic needed by (A) ?</div><div dir= =3D"auto"><br></div><div dir=3D"auto">One reason for adding (A) is "it= 's easier for the client to use/parse", which brings me again, to = the first part : what client do you have ?</div><div dir=3D"auto"><br></div= ><div dir=3D"auto">Regards</div><div dir=3D"auto"><br><div class=3D"gmail_e= xtra" dir=3D"auto"><br><div class=3D"gmail_quote"><div><div class=3D"m_-617= 6303908850086807m_-3314324299415030762h5">On Jul 10, 2017 3:21 AM, "Tr= avis Everett" <<a href=3D"mailto:[email protected]" target= =3D"_blank">[email protected]</a>> wrote:<br type=3D"attributio= n"></div></div><blockquote class=3D"m_-6176303908850086807m_-33143242994150= 30762m_5160916996955980396quote" style=3D"margin:0 0 0 .8ex;border-left:1px= #ccc solid;padding-left:1ex"><div><div class=3D"m_-6176303908850086807m_-3= 314324299415030762h5"><div dir=3D"ltr">All,<div><br></div><div>I'm resu= ming work on refining the experimental SQLite3 output. I've run into a = pretty obvious quandary that I was blissfully ignorant of:</div><div><br></= div><div>Before output-format-specific conversion, it looks like detailed d= escriptions can include (at least) a mix of HTML and raw text that still co= ntains doxygen commands (I haven't gone fishing, but my guess is that m= arkdown gets translated down to HTML, and output translators are responsibl= e for the rest).</div><div><br></div><div>When it's being served by an = SQL database, it doesn't seem like there's an "obvious" o= r "expected" format for presentational/semantic markup embedded i= n the detailed description. I was a bit surprised to find plaintext Doxygen= commands present at this stage.=C2=A0</div><div><br></div><div>I'm cur= ious if anyone has thoughts on how to handle these. The best three paths fo= rward seem to be:</div><div><br></div><div>- Saving it as XML. I'm not = keen on this since it significantly raises the bar on using the sql output,= and would require either updating all of the descriptions in place, or par= sing them into a more useful form on each use.</div><div>- Saving an opinio= nated plaintext translation. This would retain simple usability and avoid t= he update-all-descriptions or constantly-reparse issues, as long as consume= rs can live with the format ;)</div><div>- Some active, user-configurable t= ranslation method (probably translate to XML and then call a user-defined t= ranslator script as with input filters. *not sure how complex this would be= or where to start; may be getting out of my depth.</div><div><br></div><di= v>Thanks for any direction,</div><div>Travis</div></div> <br></div></div>------------------------------<wbr>------------------------= ------<wbr>------------------<br> Check out the vibrant tech community on one of the world's most<br> engaging tech sites, Slashdot.org! <a href=3D"http://sdm.link/slashdot" rel= =3D"noreferrer" target=3D"_blank">http://sdm.link/slashdot</a><br>_________= _____________________<wbr>_________________<br> Doxygen-develop mailing list<br> <a href=3D"mailto:[email protected]" target=3D"_blank">= [email protected]<wbr>rge.net</a><br> <a href=3D"https://lists.sourceforge.net/lists/listinfo/doxygen-develop" re= l=3D"noreferrer" target=3D"_blank">https://lists.sourceforge.net/<wbr>lists= /listinfo/doxygen-develop</a><br> <br></blockquote></div><br></div></div></div> </blockquote></div></div><br></div> <br>------------------------------<wbr>------------------------------<wbr>-= -----------------<br> Check out the vibrant tech community on one of the world's most<br> engaging tech sites, Slashdot.org! <a href=3D"http://sdm.link/slashdot" rel= =3D"noreferrer" target=3D"_blank">http://sdm.link/slashdot</a><br>_________= _____________________<wbr>_________________<br> Doxygen-develop mailing list<br> <a href=3D"mailto:[email protected]" target=3D"_blank">= [email protected]<wbr>rge.net</a><br> <a href=3D"https://lists.sourceforge.net/lists/listinfo/doxygen-develop" re= l=3D"noreferrer" target=3D"_blank">https://lists.sourceforge.net/<wbr>lists= /listinfo/doxygen-develop</a><br> <br></blockquote></div><br></div> </div></div></blockquote></div><br></div> --001a1137356a1e2c2d0553fa2b7e-- --===============4223389731931153872== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline ------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot --===============4223389731931153872== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Doxygen-develop mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/doxygen-develop --===============4223389731931153872==--